eth-portfolio-temp 0.3.0__cp313-cp313-win_amd64.whl

eth_portfolio/buckets.py

@@ -0,0 +1,212 @@
+import logging
+from typing import Any, Final, Optional, Set, Dict
+
+from a_sync import igather
+from eth_typing import ChecksumAddress
+from faster_async_lru import alru_cache
+from y.constants import CHAINID, STABLECOINS, WRAPPED_GAS_COIN
+from y.convert import to_address
+from y.datatypes import Address, AnyAddressType
+from y.exceptions import ContractNotVerified
+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
+from eth_portfolio._stableish import STABLEISH_COINS
+
+logger: Final = logging.getLogger(__name__)
+log_debug: Final = logger.debug
+
+SORT_AS_STABLES: Final = STABLECOINS.keys() | STABLEISH_COINS[CHAINID]
+OTHER_LONG_TERM_ASSETS: Final[Set[ChecksumAddress]] = {}.get(CHAINID, set())  # type: ignore [call-overload]
+
+
+async def get_token_bucket(
+    token: AnyAddressType, custom_buckets: Optional[Dict[str, str]] = None
+) -> 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.
+        custom_buckets: Optional mapping of token_address (lowercase) to bucket name.
+            If provided, after unwrapping the token, the function will check if the
+            unwrapped token address (lowercased) is present in this mapping and, if so,
+            return the mapped bucket name instead of using the default categorization logic.
+
+    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'
+
+        Use a custom mapping:
+
+        >>> custom_buckets = {"0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "My Stablecoin Bucket"}
+        >>> await get_token_bucket("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", custom_buckets=custom_buckets)
+        'My Stablecoin Bucket'
+
+    See Also:
+        - :func:`_unwrap_token`
+        - :func:`_is_stable`
+    """
+    token_address = to_address(token)
+    try:
+        token_address = await _unwrap_token(token_address)
+    except ContractNotVerified as e:
+        return "Other short term assets"
+
+    # Check custom mapping AFTER unwrapping
+    if custom_buckets:
+        custom_bucket = custom_buckets.get(str(token_address).lower())
+        if custom_bucket is not None:
+            return custom_bucket
+
+    if _is_stable(token_address):
+        return "Cash & cash equivalents"
+    if token_address in ETH_LIKE:
+        return "ETH"
+    if token_address in BTC_LIKE:
+        return "BTC"
+    if token_address in OTHER_LONG_TERM_ASSETS:
+        return "Other long term assets"
+    return "Other short term assets"
+
+
+@alru_cache(maxsize=None)
+async def _unwrap_token(token: Any) -> ChecksumAddress:
+    """
+    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`
+    """
+    log_debug("unwrapping %s", token)
+    if str(token) in {"ETH", "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"}:
+        log_debug("returning eee address")
+        return token
+
+    if await is_yearn_vault(token, sync=False):
+        underlying = await YearnInspiredVault(token, asynchronous=True).underlying
+        log_debug("underlying: %s", underlying)
+        return await _unwrap_token(underlying)
+    if curve and (pool := await curve.get_pool(token)):
+        pool_tokens = set(await igather(map(_unwrap_token, await pool.coins)))
+        log_debug("pool_tokens: %s", pool_tokens)
+        if pool_bucket := _pool_bucket(pool_tokens):
+            log_debug("returning pool bucket: %s", pool_bucket)
+            return pool_bucket  # type: ignore
+    if aave and await aave.is_atoken(token):
+        log_debug("atoken")
+        return str(await aave.underlying(token))
+    if compound and await compound.is_compound_market(token):
+        log_debug("unwrapping ctoken %s", token)
+        try:
+            return str(await CToken(token, asynchronous=True).underlying)
+        except AttributeError:
+            return WRAPPED_GAS_COIN
+    log_debug("returning: %s", token)
+    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`
+    """
+    log_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 < SORT_AS_STABLES:
+        return list(SORT_AS_STABLES)[0]
+    return list(INTL_STABLECOINS)[0] if pool_tokens < INTL_STABLECOINS else None
+
+
+def _is_stable(token: ChecksumAddress) -> bool:
+    """
+    Check if a token is a stablecoin or stable-ish coin.
+
+    This function checks if a given token is present in the :data:`STABLECOINS`,
+    :data:`INTL_STABLECOINS`, or :data:`STABLEISH_COINS` sets, indicating that it is
+    a stablecoin or considered stable by the wider market.
+
+    Args:
+        token: The address of the token to check.
+
+    Example:
+        Check if a token is a stablecoin or stable-ish coin:
+
+        >>> _is_stable("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
+        True
+
+    See Also:
+        - :data:`STABLECOINS`
+        - :data:`INTL_STABLECOINS`
+        - :data:`STABLEISH_COINS`
+    """
+    return token in SORT_AS_STABLES or token in INTL_STABLECOINS

eth_portfolio/constants.py

@@ -0,0 +1,82 @@
+import os
+from typing import Final
+
+from brownie import chain
+from y import Network, convert, weth
+
+ERC20_TRANSFER_EVENT_HASH: Final = (
+    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+)
+ERC677_TRANSFER_EVENT_HASH: Final = (
+    "0xe19260aff97b920c7df27010903aeb9c8d2be5d310a2c67824cf3f15396e4c16"
+)
+
+NUM_WALLETS: Final = int(os.environ.get("NUM_WALLETS", "10"))
+ADDRESSES: Final = [
+    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: Final = [ERC20_TRANSFER_EVENT_HASH, ERC677_TRANSFER_EVENT_HASH]
+
+ETH_LIKE: Final = {
+    Network.Mainnet: {
+        "ETH",
+        weth.address,
+        "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+        "0x5e74C9036fb86BD7eCdcb084a0673EFc32eA31cb",  # seth
+        "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",  # eth
+        "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",  # steth
+        "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0",  # wstETH
+        "0x9559Aaa82d9649C7A7b220E7c461d2E74c9a3593",  # reth
+        "0xE95A203B1a91a908F9B9CE46459d101078c2c3cb",  # ankreth
+        "0x04C154b66CB340F3Ae24111CC767e0184Ed00Cc6",  # pxETH
+        "0x856c4Efb76C1D1AE02e20CEB03A2A6a08b0b8dC3",  # oETH
+        "0x0100546F2cD4C9D97f798fFC9755E47865FF7Ee6",  # alETH
+        "0x1BED97CBC3c24A4fb5C069C6E311a967386131f7",  # yETH
+        "0x24Ae2dA0f361AA4BE46b48EB19C91e02c5e4f27E",  # mevETH
+        "0x5E8422345238F34275888049021821E8E08CAa1f",  # frxETH
+        "0x821A278dFff762c76410264303F25bF42e195C0C",  # pETH
+        "0xBe9895146f7AF43049ca1c1AE358B0541Ea49704",  # cbETH
+        "0xCd5fE23C85820F7B72D0926FC9b05b43E359b7ee",  # weETH
+        "0x7C07F7aBe10CE8e33DC6C5aD68FE033085256A84",  # icETH
+    },
+}.get(chain.id, set())
+
+BTC_LIKE: Final = {
+    Network.Mainnet: {
+        "0xEB4C2781e4ebA804CE9a9803C67d0893436bB27D",  # renbtc
+        "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",  # wbtc
+        "0xfE18be6b3Bd88A2D2A7f928d00292E7a9963CfC6",  # sbtc
+        "0x8064d9Ae6cDf087b1bcd5BDf3531bD5d8C537a68",  # obtc
+        "0x9BE89D2a4cd102D8Fecc6BF9dA793be995C22541",  # bbtc
+        "0x0316EB71485b0Ab14103307bf65a021042c6d380",  # hbtc
+        "0x5228a22e72ccC52d415EcFd199F99D0665E7733b",  # pbtc
+        "0x8dAEBADE922dF735c38C80C7eBD708Af50815fAa",  # tbtc
+        "0x66eFF5221ca926636224650Fd3B9c497FF828F7D",  # multiBTC
+        "0x657e8C867D8B37dCC18fA4Caead9C45EB088C642",  # eBTC
+    },
+}.get(chain.id, set())
+
+INTL_STABLECOINS: Final = {
+    Network.Mainnet: {
+        "0xD71eCFF9342A5Ced620049e616c5035F1dB98620",  # sEUR
+        "0xC581b735A1688071A1746c968e0798D642EDE491",  # EURT
+        "0xdB25f211AB05b1c97D595516F45794528a807ad8",  # EURS
+        "0x96E61422b6A9bA0e068B6c5ADd4fFaBC6a4aae27",  # ibEUR
+        "0x9fcf418B971134625CdF38448B949C8640971671",  # EURN
+        "0x39b8B6385416f4cA36a20319F70D28621895279D",  # EURe
+        "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c",  # EURC
+        "0x3F1B0278A9ee595635B61817630cC19DE792f506",  # sAUD
+        "0xFAFdF0C4c1CB09d430Bf88c75D88BB46DAe09967",  # ibAUD
+        "0x97fe22E7341a0Cd8Db6F6C021A24Dc8f4DAD855F",  # sGBP
+        "0x69681f8fde45345C3870BCD5eaf4A05a60E7D227",  # ibGBP
+        "0xF6b1C627e95BFc3c1b4c9B825a032Ff0fBf3e07d",  # sJPY
+        "0x5555f75e3d5278082200Fb451D1b6bA946D8e13b",  # ibJPY
+        "0x0F83287FF768D1c1e17a42F44d644D7F22e8ee1d",  # sCHF
+        "0x1CC481cE2BD2EC7Bf67d1Be64d4878b16078F309",  # ibCHF
+        "0x269895a3dF4D73b077Fc823dD6dA1B95f72Aaf9B",  # sKRW
+        "0x95dFDC8161832e4fF7816aC4B6367CE201538253",  # ibKRW
+    },
+}.get(chain.id, set())