"""
This module defines a set of classes to represent and manipulate various levels of balance structures
within an Ethereum portfolio. The focus of these classes is on reading, aggregating, and summarizing
balances, including the value in both tokens and their equivalent in USD.

The main classes and their purposes are as follows:

- :class:`~eth_portfolio.typing.Balance`: Represents the balance of a single token, including its token amount and equivalent USD value.
- :class:`~eth_portfolio.typing.TokenBalances`: Manages a collection of :class:`~eth_portfolio.typing.Balance` objects for multiple tokens, providing operations
  such as summing balances across tokens.
- :class:`~eth_portfolio.typing.RemoteTokenBalances`: Extends :class:`~eth_portfolio.typing.TokenBalances` to manage balances across different protocols, enabling
  aggregation and analysis of balances by protocol.
- :class:`~eth_portfolio.typing.WalletBalances`: Organizes token balances into categories such as assets, debts, and external balances
  for a single wallet. It combines :class:`~eth_portfolio.typing.TokenBalances` and :class:`~eth_portfolio.typing.RemoteTokenBalances` to provide a complete view
  of a wallet's balances.
- :class:`~eth_portfolio.typing.PortfolioBalances`: Aggregates :class:`~eth_portfolio.typing.WalletBalances` for multiple wallets, providing operations to sum
  balances across an entire portfolio.
- :class:`~eth_portfolio.typing.WalletBalancesRaw`: Similar to :class:`~eth_portfolio.typing.WalletBalances`, but with a key structure optimized for accessing
  balances directly by wallet and token.
- :class:`~eth_portfolio.typing.PortfolioBalancesByCategory`: Provides an inverted view of :class:`~eth_portfolio.typing.PortfolioBalances`, allowing access
  by category first, then by wallet and token.

These classes are designed for efficient parsing, manipulation, and summarization of portfolio data,
without managing or altering any underlying assets.
"""

from functools import cached_property
from typing import (
    Any,
    Callable,
    DefaultDict,
    Dict,
    Final,
    Iterable,
    List,
    Literal,
    Optional,
    Tuple,
    TypedDict,
    TypeVar,
    Union,
    final,
)

from checksum_dict import DefaultChecksumDict
from eth_typing import BlockNumber, HexAddress
from pandas import DataFrame, concat
from typing_extensions import ParamSpec, Self
from y import Contract, ERC20
from y.datatypes import Address

from eth_portfolio._decimal import Decimal
from eth_portfolio.typing.balance.single import Balance


_T = TypeVar("_T")
_I = TypeVar("_I")
_P = ParamSpec("_P")

Fn = Callable[_P, _T]


ProtocolLabel = str

Addresses = Union[Address, Iterable[Address]]
TokenAddress = TypeVar("TokenAddress", bound=Address)


class _SummableNonNumericMixin:
    """
    Mixin class for non-numeric summable objects.

    This class provides an interface for objects that can be used with `sum` but are not necessarily numeric.
    """

    def __add__(self, other: Self) -> Self:
        """
        Abstract method for adding two objects of the same type.

        Args:
            other: Another object of the same type.

        Raises:
            NotImplementedError: If no `__add__` method was defined on the subclass.

        Returns:
            A new object representing the sum.
        """
        raise NotImplementedError

    def __radd__(self, other: Union[Self, Literal[0]]) -> Self:
        """
        Supports the addition operation from the right side to enable use of `sum`.

        Args:
            other: Another object of the same type or zero.

        Returns:
            A new object representing the sum.

        Example:
            >>> class Summable(_SummableNonNumeric):
            ...     def __init__(self, value: int):
            ...         self.value = value
            ...     def __add__(self, other):
            ...         return Summable(self.value + other.value)
            ...     def __radd__(self, other):
            ...         return self.__add__(other)
            >>> a = Summable(10)
            >>> b = Summable(20)
            >>> sum_result = a + b
            >>> sum_result.value
            30
        """
        return self if other == 0 else self.__add__(other)  # type: ignore


_TBSeed = Union[Dict[Address, Balance], Iterable[Tuple[Address, Balance]]]


@final
class TokenBalances(DefaultChecksumDict[Balance], _SummableNonNumericMixin):  # type: ignore [misc]
    """
    A specialized defaultdict subclass made for holding a mapping of ``token -> balance``.

    Manages a collection of :class:`~eth_portfolio.typing.Balance` objects for multiple tokens, allowing for operations
    such as summing balances across tokens.

    The class uses token addresses as keys and :class:`~eth_portfolio.typing.Balance` objects as values. It supports
    arithmetic operations like addition and subtraction of token balances.

    Token addresses are checksummed automatically when adding items to the dict, and the default value for a token not present is an empty :class:`~eth_portfolio.typing.Balance` object.

    Args:
        seed: An initial seed of token balances, either as a dictionary or an iterable of tuples.

    Example:
        >>> token_balances = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
        >>> token_balances['0x123'].balance
        Decimal('100')
    """

    def __init__(
        self, seed: Optional[_TBSeed] = None, *, block: Optional[BlockNumber] = None
    ) -> None:
        super().__init__(Balance)
        self.block: Final = block
        if seed is None:
            return
        if isinstance(seed, dict):
            seed = seed.items()
        if not isinstance(seed, Iterable):
            raise TypeError(f"{seed} is not a valid input for TokenBalances")
        for token, balance in seed:  # type: ignore [misc]
            try:
                self[token] += balance
            except AttributeError:
                if not isinstance(token, (ERC20, Contract)):
                    raise
                self[token.address] += balance

    def __getitem__(self, key: HexAddress) -> Balance:
        return super().__getitem__(key) if key in self else Balance(token=key, block=self.block)

    def __setitem__(self, key: HexAddress, value: Balance) -> None:
        """
        Sets the balance for a given token address.

        Args:
            key: The token address.
            value: The balance to set for the token.

        Raises:
            TypeError: If the value is not a :class:`~eth_portfolio.typing.Balance` object.

        Example:
            >>> token_balances = TokenBalances()
            >>> token_balances['0x123'] = Balance(Decimal('100'), Decimal('2000'))
            >>> token_balances['0x123'].balance
            Decimal('100')
        """
        if not isinstance(value, Balance):
            raise TypeError(f"value must be a `Balance` object. You passed {value}") from None
        return super().__setitem__(key, value)

    @property
    def dataframe(self) -> DataFrame:
        """
        Converts the token balances into a pandas DataFrame.

        Returns:
            A DataFrame representation of the token balances.
        """
        df = DataFrame(
            {
                token: {"balance": balance.balance, "usd_value": balance.usd_value}
                for token, balance in dict.items(self)
            }
        ).T
        df.reset_index(inplace=True)
        df.rename(columns={"index": "token"}, inplace=True)
        return df

    def sum_usd(self) -> Decimal:
        """
        Sums the USD values of all token balances.

        Returns:
            The total USD value of all token balances.

        Example:
            >>> token_balances = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
            >>> total_usd = token_balances.sum_usd()
            >>> total_usd
            Decimal('2000')
        """
        return Decimal(sum(balance.usd for balance in dict.values(self)))

    def __bool__(self) -> bool:
        """
        Evaluates the truth value of the :class:`~eth_portfolio.typing.TokenBalances` object.

        Returns:
            True if any token has a non-zero balance, otherwise False.

        Example:
            >>> token_balances = TokenBalances()
            >>> bool(token_balances)
            False
        """
        return any(dict.values(self))

    def __repr__(self) -> str:
        """
        Returns a string representation of the :class:`~eth_portfolio.typing.TokenBalances` object.

        Returns:
            The string representation of the token balances.
        """
        return f"TokenBalances{dict(self)}"

    def __add__(self, other: "TokenBalances") -> "TokenBalances":
        """
        Adds another :class:`~eth_portfolio.typing.TokenBalances` object to this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.TokenBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.TokenBalances` object with the combined balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.TokenBalances`.

        Example:
            >>> tb1 = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
            >>> tb2 = TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})
            >>> combined_tb = tb1 + tb2
            >>> combined_tb['0x123'].balance
            Decimal('150')
        """
        if not isinstance(other, TokenBalances):
            raise TypeError(f"{other} is not a TokenBalances object")

        block = self.block
        if block != other.block:
            raise ValueError(
                f"These TokenBalances objects are not from the same block ({block} and {other.block})"
            )

        combined: TokenBalances = TokenBalances(block=block)
        for token, balance in dict.items(self):
            if balance:
                DefaultChecksumDict._setitem_nochecksum(
                    combined,
                    token,
                    Balance(balance.balance, balance.usd_value, token=token, block=block),
                )
        for token, balance in dict.items(other):
            if balance:
                if token in combined:
                    DefaultChecksumDict._setitem_nochecksum(
                        combined, token, combined._getitem_nochecksum(token) + balance
                    )
                else:
                    DefaultChecksumDict._setitem_nochecksum(
                        combined,
                        token,
                        Balance(balance.balance, balance.usd_value, token=token, block=block),
                    )
        return combined

    def __iadd__(self, other: "TokenBalances") -> "TokenBalances":
        if not isinstance(other, TokenBalances):
            raise TypeError(f"{other} is not a TokenBalances object")

        block = self.block
        if block != other.block:
            raise ValueError(
                f"These TokenBalances objects are not from the same block ({block} and {other.block})"
            )

        for token, balance in dict.items(other):
            if not balance:
                continue
            if token in self:
                DefaultChecksumDict._setitem_nochecksum(
                    self,
                    token,
                    self._getitem_nochecksum(token) + balance,
                )
            else:
                balance = Balance(balance.balance, balance.usd_value, token=token, block=block)
                DefaultChecksumDict._setitem_nochecksum(self, token, balance)
        return self

    def __sub__(self, other: "TokenBalances") -> "TokenBalances":
        """
        Subtracts another :class:`~eth_portfolio.typing.TokenBalances` object from this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.TokenBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.TokenBalances` object with the subtracted balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.TokenBalances`.

        Example:
            >>> tb1 = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
            >>> tb2 = TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})
            >>> result_tb = tb1 - tb2
            >>> result_tb['0x123'].balance
            Decimal('50')
        """
        if not isinstance(other, TokenBalances):
            raise TypeError(f"{other} is not a TokenBalances object")
        if self.block != other.block:
            raise ValueError(
                f"These TokenBalances objects are not from the same block ({self.block} and {other.block})"
            )
        # NOTE We need a new object to avoid mutating the inputs
        subtracted: TokenBalances = TokenBalances(self, block=self.block)
        for token, balance in dict.items(other):
            subtracted[token] -= balance
        for token, balance in dict(subtracted).items():
            if not balance:
                del subtracted[token]
        return subtracted

    __slots__ = ("block",)


_RTBSeed = Dict[ProtocolLabel, TokenBalances]


@final
class RemoteTokenBalances(DefaultDict[ProtocolLabel, TokenBalances], _SummableNonNumericMixin):
    """
    Manages token balances across different protocols, extending the :class:`~eth_portfolio.typing.TokenBalances` functionality
    to multiple protocols.

    The class uses protocol labels as keys and :class:`~eth_portfolio.typing.TokenBalances` objects as values.

    Args:
        seed: An initial seed of remote token balances, either as a dictionary
            or an iterable of tuples.

    Example:
        >>> remote_balances = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
        >>> remote_balances['protocol1']['0x123'].balance
        Decimal('100')
    """

    __slots__ = ("block",)

    def __init__(
        self, seed: Optional[_RTBSeed] = None, *, block: Optional[BlockNumber] = None
    ) -> None:
        super().__init__(lambda: TokenBalances(block=block))
        self.block: Final = block
        if seed is None:
            return
        if isinstance(seed, dict):
            seed = seed.items()  # type: ignore [assignment]
        if not isinstance(seed, Iterable):
            raise TypeError(f"{seed} is not a valid input for TokenBalances")
        for remote, token_balances in seed:  # type: ignore [misc]
            if self.block != token_balances.block:
                raise ValueError(
                    f"These objects are not from the same block ({self.block} and {token_balances.block})"
                )
            self[remote] += token_balances  # type: ignore [has-type]

    def __setitem__(self, protocol: str, value: TokenBalances) -> None:
        """
        Sets the token balances for a given protocol.

        Args:
            key: The protocol label.
            value: The token balances to set for the protocol.

        Raises:
            TypeError: If the value is not a :class:`~eth_portfolio.typing.TokenBalances` object.

        Example:
            >>> remote_balances = RemoteTokenBalances()
            >>> remote_balances['protocol1'] = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
            >>> remote_balances['protocol1']['0x123'].balance
            Decimal('100')
        """
        if not isinstance(value, TokenBalances):
            raise TypeError(f"value must be a `TokenBalances` object. You passed {value}") from None
        return super().__setitem__(protocol, value)

    @property
    def dataframe(self) -> DataFrame:
        """
        Converts the remote token balances into a pandas DataFrame.

        Returns:
            A DataFrame representation of the remote token balances.
        """
        dfs: List[DataFrame] = []
        for protocol, balances in dict.items(self):
            df = balances.dataframe
            df["protocol"] = protocol
            dfs.append(df)
        return concat(dfs).reset_index(drop=True) if dfs else DataFrame()

    def sum_usd(self) -> Decimal:
        """
        Sums the USD values of all token balances across all protocols.

        Returns:
            The total USD value of all remote token balances.

        Example:
            >>> remote_balances = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> total_usd = remote_balances.sum_usd()
            >>> total_usd
            Decimal('2000')
        """
        return Decimal(sum(balance.sum_usd() for balance in dict.values(self)))

    def __bool__(self) -> bool:
        """
        Evaluates the truth value of the :class:`~eth_portfolio.typing.RemoteTokenBalances` object.

        Returns:
            True if any protocol has a non-zero balance, otherwise False.

        Example:
            >>> remote_balances = RemoteTokenBalances()
            >>> bool(remote_balances)
            False
        """
        return any(dict.values(self))

    def __repr__(self) -> str:
        """
        Returns a string representation of the :class:`~eth_portfolio.typing.RemoteTokenBalances` object.

        Returns:
            The string representation of the remote token balances.
        """
        return f"RemoteTokenBalances{dict(self)}"

    def __add__(self, other: "RemoteTokenBalances") -> "RemoteTokenBalances":
        """
        Adds another :class:`~eth_portfolio.typing.RemoteTokenBalances` object to this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.RemoteTokenBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.RemoteTokenBalances` object with the combined balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.RemoteTokenBalances`.

        Example:
            >>> rb1 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> rb2 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
            >>> combined_rb = rb1 + rb2
            >>> combined_rb['protocol1']['0x123'].balance
            Decimal('150')
        """
        if not isinstance(other, RemoteTokenBalances):
            raise TypeError(f"{other} is not a RemoteTokenBalances object")

        block = self.block
        if block != other.block:
            raise ValueError(
                f"These RemoteTokenBalances objects are not from the same block ({block} and {other.block})"
            )

        combined: RemoteTokenBalances = RemoteTokenBalances(block=block)
        for protocol, token_balances in dict.items(self):
            if token_balances:
                combined[protocol] += token_balances
        for protocol, token_balances in dict.items(other):
            if token_balances:
                combined[protocol] += token_balances
        return combined

    def __iadd__(self, other: "RemoteTokenBalances") -> "RemoteTokenBalances":
        if not isinstance(other, RemoteTokenBalances):
            raise TypeError(f"{other} is not a RemoteTokenBalances object")

        if self.block != other.block:
            raise ValueError(
                f"These RemoteTokenBalances objects are not from the same block ({self.block} and {other.block})"
            )

        for protocol, token_balances in dict.items(other):
            if token_balances:
                self[protocol] += token_balances
        return self

    def __sub__(self, other: "RemoteTokenBalances") -> "RemoteTokenBalances":
        """
        Subtracts another :class:`~eth_portfolio.typing.RemoteTokenBalances` object from this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.RemoteTokenBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.RemoteTokenBalances` object with the subtracted balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.RemoteTokenBalances`.

        Example:
            >>> rb1 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> rb2 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
            >>> result_rb = rb1 - rb2
            >>> result_rb['protocol1']['0x123'].balance
            Decimal('50')
        """
        if not isinstance(other, RemoteTokenBalances):
            raise TypeError(f"{other} is not a RemoteTokenBalances object")
        if self.block != other.block:
            raise ValueError(
                f"These RemoteTokenBalances objects are not from the same block ({self.block} and {other.block})"
            )
        # NOTE We need a new object to avoid mutating the inputs
        subtracted: RemoteTokenBalances = RemoteTokenBalances(self, block=self.block)
        for protocol, token_balances in dict.items(other):
            subtracted[protocol] -= token_balances
        for protocol, token_balances in dict(subtracted).items():
            if not token_balances:
                del subtracted[protocol]
        return subtracted


CategoryLabel = Literal["assets", "debt", "external"]

_WalletBalancesTD = TypedDict(
    "_WalletBalancesTD",
    {
        "assets": TokenBalances,
        "debt": TokenBalances,
        "external": RemoteTokenBalances,
    },
)

_WBSeed = Union[_WalletBalancesTD, Iterable[Tuple[CategoryLabel, TokenBalances]]]


@final
class WalletBalances(
    Dict[CategoryLabel, Union[TokenBalances, RemoteTokenBalances]], _SummableNonNumericMixin
):
    """
    Organizes token balances into categories such as assets, debts, and external balances for a single wallet.

    The class uses categories as keys (`assets`, `debt`, `external`) and :class:`~eth_portfolio.typing.TokenBalances` or :class:`~eth_portfolio.typing.RemoteTokenBalances`
    objects as values.

    Args:
        seed: An initial seed of wallet balances, either as a dictionary or an iterable of tuples.

    Example:
        >>> wallet_balances = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
        >>> wallet_balances['assets']['0x123'].balance
        Decimal('100')
    """

    def __init__(
        self,
        seed: Optional[Union["WalletBalances", _WBSeed]] = None,
        *,
        block: Optional[BlockNumber] = None,
    ) -> None:
        self.block: Final = block
        self._keys = "assets", "debt", "external"
        self["assets"] = TokenBalances(block=block)
        self["debt"] = RemoteTokenBalances(block=block)
        self["external"] = RemoteTokenBalances(block=block)

        if seed is None:
            return
        if isinstance(seed, dict):
            seed = seed.items()  # type: ignore
        if not isinstance(seed, Iterable):
            raise TypeError(f"{seed} is not a valid input for WalletBalances")
        for key, balances in seed:  # type: ignore
            if self.block != balances.block:
                raise ValueError(
                    f"These objects are not from the same block ({self.block} and {balances.block})"
                )
            self.__validateitem(key, balances)
            self[key] += balances  # type: ignore [operator]

    @property
    def assets(self) -> TokenBalances:
        """
        Returns the assets held by the wallet.

        Returns:
            :class:`~eth_portfolio.typing.TokenBalances`: The :class:`~eth_portfolio.typing.TokenBalances` object representing the wallet's assets.
        """
        return self["assets"]  # type: ignore

    @property
    def debt(self) -> RemoteTokenBalances:
        """
        Returns the debts associated with the wallet.

        Returns:
            :class:`~eth_portfolio.typing.RemoteTokenBalances`: The :class:`~eth_portfolio.typing.RemoteTokenBalances` object representing the wallet's debts.
        """
        return self["debt"]

    @property
    def external(self) -> RemoteTokenBalances:
        """
        Returns the external balances associated with the wallet.

        Returns:
            :class:`~eth_portfolio.typing.RemoteTokenBalances`: The :class:`~eth_portfolio.typing.RemoteTokenBalances` object representing the wallet's external balances.
        """
        return self["external"]

    @property
    def dataframe(self) -> DataFrame:
        """
        Converts the wallet balances into a pandas DataFrame.

        Returns:
            A DataFrame representation of the wallet balances.
        """
        dfs: List[DataFrame] = []
        for category, category_bals in dict.items(self):
            df = category_bals.dataframe
            df["category"] = category
            dfs.append(df)
        return concat(dfs).reset_index(drop=True) if dfs else DataFrame()

    def sum_usd(self) -> Decimal:
        """
        Sums the USD values of the wallet's assets, debts, and external balances.

        Returns:
            The total USD value of the wallet's net assets (assets - debt + external).

        Example:
            >>> wallet_balances = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> total_usd = wallet_balances.sum_usd()
            >>> total_usd
            Decimal('2000')
        """
        return self.assets.sum_usd() - self.debt.sum_usd() + self.external.sum_usd()

    def __bool__(self) -> bool:
        """
        Evaluates the truth value of the :class:`~eth_portfolio.typing.WalletBalances` object.

        Returns:
            True if any category has a non-zero balance, otherwise False.

        Example:
            >>> wallet_balances = WalletBalances()
            >>> bool(wallet_balances)
            False
        """
        return any(dict.values(self))

    def __repr__(self) -> str:
        """
        Returns a string representation of the :class:`~eth_portfolio.typing.WalletBalances` object.

        Returns:
            The string representation of the wallet balances.
        """
        return f"WalletBalances {dict(self)}"

    def __add__(self, other: "WalletBalances") -> "WalletBalances":
        """
        Adds another :class:`~eth_portfolio.typing.WalletBalances` object to this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.WalletBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.WalletBalances` object with the combined balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalances`.

        Example:
            >>> wb1 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> wb2 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
            >>> combined_wb = wb1 + wb2
            >>> combined_wb['assets']['0x123'].balance
            Decimal('150')
        """
        if not isinstance(other, WalletBalances):
            raise TypeError(f"{other} is not a WalletBalances object")

        block = self.block
        if block != other.block:
            raise ValueError(
                f"These WalletBalances objects are not from the same block ({block} and {other.block})"
            )

        combined: WalletBalances = WalletBalances(block=block)
        for category, balances in dict.items(self):
            if balances:
                combined[category] += balances  # type: ignore [operator]
        for category, balances in dict.items(other):
            if balances:
                combined[category] += balances  # type: ignore [operator]
        return combined

    def __iadd__(self, other: "WalletBalances") -> "WalletBalances":
        if not isinstance(other, WalletBalances):
            raise TypeError(f"{other} is not a WalletBalances object")

        if self.block != other.block:
            raise ValueError(
                f"These WalletBalances objects are not from the same block ({self.block} and {other.block})"
            )

        for category, balances in dict.items(other):
            if balances:
                self[category] += balances  # type: ignore [operator]
        return self

    def __sub__(self, other: "WalletBalances") -> "WalletBalances":
        """
        Subtracts another :class:`~eth_portfolio.typing.WalletBalances` object from this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.WalletBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.WalletBalances` object with the subtracted balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalances`.

        Example:
            >>> wb1 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> wb2 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
            >>> result_wb = wb1 - wb2
            >>> result_wb['assets']['0x123'].balance
            Decimal('50')
        """
        if not isinstance(other, WalletBalances):
            raise TypeError(f"{other} is not a WalletBalances object")
        if self.block != other.block:
            raise ValueError(
                f"These WalletBalances objects are not from the same block ({self.block} and {other.block})"
            )
        # We need a new object to avoid mutating the inputs
        subtracted: WalletBalances = WalletBalances(self, block=self.block)
        for category, balances in dict.items(other):
            subtracted[category] -= balances  # type: ignore
        for category, balances in dict(subtracted).items():
            if not balances:
                del subtracted[category]
        return subtracted

    def __getitem__(self, key: CategoryLabel) -> Union[TokenBalances, RemoteTokenBalances]:
        """
        Retrieves the balance associated with the given category key.

        Args:
            key: The category label (`assets`, `debt`, or `external`).

        Returns:
            The balances associated with the category.

        Raises:
            KeyError: If the key is not a valid category.

        Example:
            >>> wallet_balances = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> assets_balances = wallet_balances['assets']
            >>> assets_balances['0x123'].balance
            Decimal('100')
        """
        self.__validatekey(key)
        return super().__getitem__(key)

    def __setitem__(
        self, key: CategoryLabel, value: Union[TokenBalances, RemoteTokenBalances]
    ) -> None:
        """
        Sets the balance associated with the given category key.

        Args:
            key: The category label (`assets`, `debt`, or `external`).
            value: The balance to associate with the category.

        Raises:
            KeyError: If the key is not a valid category.
            TypeError: If the value is not a valid balance type for the category.

        Example:
            >>> wallet_balances = WalletBalances()
            >>> wallet_balances['assets'] = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
            >>> wallet_balances['assets']['0x123'].balance
            Decimal('100')
        """
        self.__validateitem(key, value)
        return super().__setitem__(key, value)

    def __validatekey(self, key: CategoryLabel) -> None:
        """
        Validates that the given key is a valid category.

        Valid keys: "assets", "debt", "external"

        Args:
            key: The category label to validate.

        Raises:
            KeyError: If the key is not a valid category.
        """
        if key not in self._keys:
            raise KeyError(
                f"{key} is not a valid key for WalletBalances. Valid keys are: {self._keys}"
            )

    def __validateitem(self, key: CategoryLabel, item: Any) -> None:
        """
        Validates that the given item is a valid balance type for the category.

        Args:
            key: The category label.
            item: The balance item to validate.

        Raises:
            KeyError: If the key is not a valid category.
            TypeError: If the item is not a valid balance type for the category.
        """
        self.__validatekey(key)
        if key == "assets":
            if not isinstance(item, TokenBalances):
                raise TypeError(
                    f'{item} is not a valid value for "{key}". Must be a TokenBalances object.'
                )
        elif key in {"debt", "external"}:
            if not isinstance(item, RemoteTokenBalances):
                raise TypeError(
                    f'{item} is not a valid value for "{key}". Must be a RemoteTokenBalances object.'
                )
        else:
            raise NotImplementedError(f"key {key} is not yet implemented.")


_PBSeed = Union[Dict[Address, WalletBalances], Iterable[Tuple[Address, WalletBalances]]]


@final
class PortfolioBalances(DefaultChecksumDict[WalletBalances], _SummableNonNumericMixin):  # type: ignore [misc]
    """
    Aggregates :class:`~eth_portfolio.typing.WalletBalances` for multiple wallets, providing operations to sum
    balances across an entire portfolio.

    The class uses wallet addresses as keys and :class:`~eth_portfolio.typing.WalletBalances` objects as values.

    Args:
        seed: An initial seed of portfolio balances, either as a dictionary or an iterable of tuples.

    Example:
        >>> portfolio_balances = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x456': Balance(Decimal('100'), Decimal('2000'))})})})
        >>> portfolio_balances['0x123']['assets']['0x456'].balance
        Decimal('100')
    """

    def __init__(
        self, seed: Optional[_PBSeed] = None, *, block: Optional[BlockNumber] = None
    ) -> None:
        super().__init__(lambda: WalletBalances(block=block))
        self.block: Final = block
        if seed is None:
            return
        if isinstance(seed, dict):
            seed = seed.items()
        if not isinstance(seed, Iterable):
            raise TypeError(f"{seed} is not a valid input for PortfolioBalances")
        for wallet, balances in seed:
            if self.block != balances.block:
                raise ValueError(
                    f"These objects are not from the same block ({self.block} and {balances.block})"
                )
            self[wallet] += balances

    def __setitem__(self, key: HexAddress, value: WalletBalances) -> None:
        if not isinstance(value, WalletBalances):
            raise TypeError(
                f"value must be a `WalletBalances` object. You passed {value}"
            ) from None
        return super().__setitem__(key, value)

    @property
    def dataframe(self) -> DataFrame:
        """
        Converts the portfolio balances into a pandas DataFrame.

        Returns:
            A DataFrame representation of the portfolio balances.
        """
        dfs: List[DataFrame] = []
        for wallet, balances in dict.items(self):
            df = balances.dataframe
            df["wallet"] = wallet
            dfs.append(df)
        return concat(dfs).reset_index(drop=True) if dfs else DataFrame()

    def sum_usd(self) -> Decimal:
        """
        Sums the USD values of all wallet balances in the portfolio.

        Returns:
            The total USD value of all wallet balances in the portfolio.

        Example:
            >>> portfolio_balances = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
            >>> total_usd = portfolio_balances.sum_usd()
            >>> total_usd
            Decimal('2000')
        """
        return sum(balances.sum_usd() for balances in dict.values(self))  # type: ignore

    @cached_property
    def inverted(self) -> "PortfolioBalancesByCategory":
        """
        Returns an inverted view of the portfolio balances, grouped by category first.

        Returns:
            :class:`~eth_portfolio.typing.PortfolioBalancesByCategory`: The inverted portfolio balances, grouped by category.

        Example:
            >>> portfolio_balances = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
            >>> inverted_pb = portfolio_balances.inverted
            >>> inverted_pb['assets']['0x123'].balance
            Decimal('100')
        """
        inverted = PortfolioBalancesByCategory()
        for wallet, wbalances in dict.items(self):
            for label, tbalances in wbalances.items():
                if tbalances:
                    inverted[label][wallet] += tbalances  # type: ignore [operator]
        return inverted

    def __bool__(self) -> bool:
        """
        Evaluates the truth value of the :class:`~eth_portfolio.typing.PortfolioBalances` object.

        Returns:
            True if any wallet has a non-zero balance of any token, otherwise False.

        Example:
            >>> portfolio_balances = PortfolioBalances()
            >>> bool(portfolio_balances)
            False
        """
        return any(dict.values(self))

    def __repr__(self) -> str:
        """
        Returns a string representation of the :class:`~eth_portfolio.typing.PortfolioBalances` object.

        Returns:
            The string representation of the portfolio balances.
        """
        return f"WalletBalances{dict(self)}"

    def __add__(self, other: "PortfolioBalances") -> "PortfolioBalances":
        """
        Adds another :class:`~eth_portfolio.typing.PortfolioBalances` object to this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.PortfolioBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.PortfolioBalances` object with the combined balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalances`.

        Example:
            >>> pb1 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
            >>> pb2 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
            >>> combined_pb = pb1 + pb2
            >>> combined_pb['0x123']['assets']['0x123'].balance
            Decimal('150')
        """
        if not isinstance(other, PortfolioBalances):
            raise TypeError(f"{other} is not a PortfolioBalances object")

        block = self.block
        if block != other.block:
            raise ValueError(
                f"These PortfolioBalances objects are not from the same block ({block} and {other.block})"
            )
        # NOTE We need a new object to avoid mutating the inputs
        combined: PortfolioBalances = PortfolioBalances(block=block)
        for wallet, balance in dict.items(self):
            if balance:
                DefaultChecksumDict._setitem_nochecksum(
                    combined, wallet, combined._getitem_nochecksum(wallet) + balance
                )
        for wallet, balance in dict.items(other):
            if balance:
                DefaultChecksumDict._setitem_nochecksum(
                    combined, wallet, combined._getitem_nochecksum(wallet) + balance
                )
        return combined

    def __iadd__(self, other: "PortfolioBalances") -> "PortfolioBalances":
        if not isinstance(other, PortfolioBalances):
            raise TypeError(f"{other} is not a PortfolioBalances object")

        if self.block != other.block:
            raise ValueError(
                f"These PortfolioBalances objects are not from the same block ({self.block} and {other.block})"
            )

        for wallet, balance in dict.items(other):
            if balance:
                DefaultChecksumDict._setitem_nochecksum(
                    self, wallet, self._getitem_nochecksum(wallet) + balance
                )
        return self

    def __sub__(self, other: "PortfolioBalances") -> "PortfolioBalances":
        """
        Subtracts another :class:`~eth_portfolio.typing.PortfolioBalances` object from this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.PortfolioBalances` object.

        Returns:
            A new :class:`~eth_portfolio.typing.PortfolioBalances` object with the subtracted balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalances`.

        Example:
            >>> pb1 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
            >>> pb2 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
            >>> result_pb = pb1 - pb2
            >>> result_pb['0x123']['assets']['0x123'].balance
            Decimal('50')
        """
        if not isinstance(other, PortfolioBalances):
            raise TypeError(f"{other} is not a PortfolioBalances object")
        if self.block != other.block:
            raise ValueError(
                f"These PortfolioBalances objects are not from the same block ({self.block} and {other.block})"
            )
        # We need a new object to avoid mutating the inputs
        subtracted: PortfolioBalances = PortfolioBalances(self, block=self.block)
        for protocol, balances in dict.items(other):
            subtracted[protocol] -= balances
        for protocol, balances in subtracted.items():
            if not balances:
                del subtracted[protocol]
        return subtracted

    __slots__ = ("block",)


_WTBInput = Union[Dict[Address, TokenBalances], Iterable[Tuple[Address, TokenBalances]]]


@final
class WalletBalancesRaw(DefaultChecksumDict[TokenBalances], _SummableNonNumericMixin):  # type: ignore [misc]
    # Since PortfolioBalances key lookup is:    ``wallet   -> category -> token    -> balance``
    # We need a new structure for key pattern:  ``wallet   -> token    -> balance``

    # WalletBalancesRaw fills this role.
    """
    A structure for key pattern `wallet -> token -> balance`.

    This class is similar to :class:`~eth_portfolio.typing.WalletBalances` but optimized for key lookups by wallet and token directly.
    It manages :class:`~eth_portfolio.typing.TokenBalances` objects for multiple wallets.

    Args:
        seed: An initial seed of wallet balances, either as a dictionary or an iterable of tuples.

    Example:
        >>> raw_balances = WalletBalancesRaw({'0x123': TokenBalances({'0x456': Balance(Decimal('100'), Decimal('2000'))})})
        >>> raw_balances['0x123']['0x456'].balance
        Decimal('100')
    """

    def __init__(
        self, seed: Optional[_WTBInput] = None, *, block: Optional[BlockNumber] = None
    ) -> None:
        super().__init__(lambda: TokenBalances(block=block))
        self.block: Final = block
        if seed is None:
            return
        if isinstance(seed, dict):
            seed = seed.items()
        if not isinstance(seed, Iterable):
            raise TypeError(f"{seed} is not a valid input for WalletBalancesRaw")
        for wallet, balances in seed:
            if self.block != balances.block:
                raise ValueError(
                    f"These objects are not from the same block ({self.block} and {balances.block})"
                )
            self[wallet] += balances

    def __bool__(self) -> bool:
        """
        Evaluates the truth value of the :class:`~eth_portfolio.typing.WalletBalancesRaw` object.

        Returns:
            True if any wallet has a non-zero balance, otherwise False.

        Example:
            >>> raw_balances = WalletBalancesRaw()
            >>> bool(raw_balances)
            False
        """
        return any(dict.values(self))

    def __repr__(self) -> str:
        """
        Returns a string representation of the :class:`~eth_portfolio.typing.WalletBalancesRaw` object.

        Returns:
            The string representation of the raw wallet balances.
        """
        return f"WalletBalances{dict(self)}"

    def __add__(self, other: "WalletBalancesRaw") -> "WalletBalancesRaw":
        """
        Adds another :class:`~eth_portfolio.typing.WalletBalancesRaw` object to this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.WalletBalancesRaw` object.

        Returns:
            A new :class:`~eth_portfolio.typing.WalletBalancesRaw` object with the combined balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalancesRaw`.

        Example:
            >>> raw_balances1 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> raw_balances2 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
            >>> combined_raw = raw_balances1 + raw_balances2
            >>> combined_raw['0x123']['0x123'].balance
            Decimal('150')
        """
        if not isinstance(other, WalletBalancesRaw):
            raise TypeError(f"{other} is not a WalletBalancesRaw object")

        block = self.block
        if block != other.block:
            raise ValueError(
                f"These WalletBalancesRaw objects are not from the same block ({block} and {other.block})"
            )

        combined: WalletBalancesRaw = WalletBalancesRaw(block=block)
        for wallet, balance in dict.items(self):
            if balance:
                DefaultChecksumDict._setitem_nochecksum(
                    combined, wallet, combined._getitem_nochecksum(wallet) + balance
                )
        for wallet, balance in dict.items(other):
            if balance:
                DefaultChecksumDict._setitem_nochecksum(
                    combined, wallet, combined._getitem_nochecksum(wallet) + balance
                )
        return combined

    def __iadd__(self, other: "WalletBalancesRaw") -> "WalletBalancesRaw":
        if not isinstance(other, WalletBalancesRaw):
            raise TypeError(f"{other} is not a WalletBalancesRaw object")

        if self.block != other.block:
            raise ValueError(
                f"These WalletBalancesRaw objects are not from the same block ({self.block} and {other.block})"
            )

        for wallet, balance in dict.items(other):
            if balance:
                DefaultChecksumDict._setitem_nochecksum(
                    self, wallet, self._getitem_nochecksum(wallet) + balance
                )
        return self

    def __sub__(self, other: "WalletBalancesRaw") -> "WalletBalancesRaw":
        """
        Subtracts another :class:`~eth_portfolio.typing.WalletBalancesRaw` object from this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.WalletBalancesRaw` object.

        Returns:
            A new :class:`~eth_portfolio.typing.WalletBalancesRaw` object with the subtracted balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalancesRaw`.

        Example:
            >>> raw_balances1 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
            >>> raw_balances2 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
            >>> result_raw = raw_balances1 - raw_balances2
            >>> result_raw['0x123']['0x123'].balance
            Decimal('50')
        """
        if not isinstance(other, WalletBalancesRaw):
            raise TypeError(f"{other} is not a WalletBalancesRaw object")
        if self.block != other.block:
            raise ValueError(
                f"These WalletBalancesRaw objects are not from the same block ({self.block} and {other.block})"
            )
        # NOTE We need a new object to avoid mutating the inputs
        subtracted: WalletBalancesRaw = WalletBalancesRaw(self, block=other.block)
        for wallet, balances in dict.items(other):
            if balances:
                subtracted[wallet] -= balances
        for wallet, balances in subtracted.items():
            if not balances:
                del subtracted[wallet]
        return subtracted

    __slots__ = ("block",)


_CBInput = Union[
    Dict[CategoryLabel, WalletBalancesRaw], Iterable[Tuple[CategoryLabel, WalletBalancesRaw]]
]


@final
class PortfolioBalancesByCategory(
    DefaultDict[CategoryLabel, WalletBalancesRaw], _SummableNonNumericMixin
):
    """
    Provides an inverted view of :class:`~eth_portfolio.typing.PortfolioBalances`, allowing access by category first,
    then by wallet and token.

    The class uses category labels as keys (`assets`, `debt`, `external`) and :class:`~eth_portfolio.typing.WalletBalancesRaw`
    objects as values.

    Args:
        seed: An initial seed of portfolio balances by category, either as a dictionary or an iterable of tuples.

    Example:
        >>> pb_by_category = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x456': Balance(Decimal('100'), Decimal('2000'))})})})
        >>> pb_by_category['assets']['0x123']['0x456'].balance
        Decimal('100')
    """

    def __init__(
        self, seed: Optional[_CBInput] = None, *, block: Optional[BlockNumber] = None
    ) -> None:
        super().__init__(lambda: WalletBalancesRaw(block=block))
        self.block: Final = block
        if seed is None:
            return
        if isinstance(seed, dict):
            seed = seed.items()
        if not isinstance(seed, Iterable):
            raise TypeError(f"{seed} is not a valid input for PortfolioBalancesByCategory")
        for label, balances in seed:  # type: ignore
            if self.block != balances.block:
                raise ValueError(
                    f"These objects are not from the same block ({self.block} and {balances.block})"
                )
            self[label] += balances

    @property
    def assets(self) -> WalletBalancesRaw:
        """
        Returns the asset balances across all wallets.

        Returns:
            :class:`~eth_portfolio.typing.WalletBalancesRaw`: The :class:`~eth_portfolio.typing.WalletBalancesRaw` object representing the asset balances.
        """
        return self["assets"]

    @property
    def debt(self) -> WalletBalancesRaw:
        """
        Returns the debt balances across all wallets.

        Returns:
            :class:`~eth_portfolio.typing.WalletBalancesRaw`: The :class:`~eth_portfolio.typing.WalletBalancesRaw` object representing the debt balances.
        """
        return self["debt"]

    def invert(self) -> "PortfolioBalances":
        """
        Inverts the portfolio balances by category to group by wallet first.

        Returns:
            :class:`~eth_portfolio.typing.PortfolioBalances`: The inverted portfolio balances, grouped by wallet first.

        Example:
            >>> pb_by_category = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
            >>> inverted_pb = pb_by_category.invert()
            >>> inverted_pb['0x123']['assets']['0x123'].balance
            Decimal('100')
        """
        inverted = PortfolioBalances()
        for label, wtbalances in dict.items(self):
            for wallet, tbalances in wtbalances.items():
                if tbalances:
                    inverted[wallet][label] += tbalances  # type: ignore [operator]
        return inverted

    def __bool__(self) -> bool:
        """
        Evaluates the truth value of the :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.

        Returns:
            True if any category has a non-zero balance, otherwise False.

        Example:
            >>> pb_by_category = PortfolioBalancesByCategory()
            >>> bool(pb_by_category)
            False
        """
        return any(dict.values(self))

    def __repr__(self) -> str:
        """
        Returns a string representation of the :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.

        Returns:
            The string representation of the portfolio balances by category.
        """
        return f"PortfolioBalancesByCategory{dict(self)}"

    def __add__(self, other: "PortfolioBalancesByCategory") -> "PortfolioBalancesByCategory":
        """
        Adds another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object to this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.

        Returns:
            A new :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object with the combined balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalancesByCategory`.

        Example:
            >>> pb_by_category1 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
            >>> pb_by_category2 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
            >>> combined_pb_by_category = pb_by_category1 + pb_by_category2
            >>> combined_pb_by_category['assets']['0x123']['0x123'].balance
            Decimal('150')
        """
        if not isinstance(other, PortfolioBalancesByCategory):
            raise TypeError(f"{other} is not a PortfolioBalancesByCategory object")

        block = self.block
        if block != other.block:
            raise ValueError(
                f"These PortfolioBalancesByCategory objects are not from the same block ({block} and {other.block})"
            )

        combined: PortfolioBalancesByCategory = PortfolioBalancesByCategory(block=block)
        for protocol, balances in dict.items(self):
            if balances:
                combined[protocol] += balances
        for protocol, balances in dict.items(other):
            if balances:
                combined[protocol] += balances
        return combined

    def __iadd__(self, other: "PortfolioBalancesByCategory") -> "PortfolioBalancesByCategory":

        if not isinstance(other, PortfolioBalancesByCategory):
            raise TypeError(f"{other} is not a PortfolioBalancesByCategory object")

        if self.block != other.block:
            raise ValueError(
                f"These PortfolioBalancesByCategory objects are not from the same block ({self.block} and {other.block})"
            )

        for protocol, balances in dict.items(other):
            if balances:
                self[protocol] += balances
        return self

    def __sub__(self, other: "PortfolioBalancesByCategory") -> "PortfolioBalancesByCategory":
        """
        Subtracts another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object from this one.

        Args:
            other: Another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.

        Returns:
            A new :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object with the subtracted balances.

        Raises:
            TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalancesByCategory`.

        Example:
            >>> pb_by_category1 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
            >>> pb_by_category2 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
            >>> result_pb_by_category = pb_by_category1 - pb_by_category2
            >>> result_pb_by_category['assets']['0x123']['0x123'].balance
            Decimal('50')
        """
        if not isinstance(other, PortfolioBalancesByCategory):
            raise TypeError(f"{other} is not a PortfolioBalancesByCategory object")
        if self.block != other.block:
            raise ValueError(
                f"These PortfolioBalancesByCategory objects are not from the same block ({self.block} and {other.block})"
            )
        # NOTE We need a new object to avoid mutating the inputs
        subtracted: PortfolioBalancesByCategory = PortfolioBalancesByCategory(
            self, block=self.block
        )
        for protocol, balances in dict.items(other):
            subtracted[protocol] -= balances
        for protocol, balances in subtracted.items():
            if not balances:
                del subtracted[protocol]
        return subtracted
