DeFiProtocolInterface.py

"""
DeFiProtocolInterface.py
========================
Abstract Base Class that defines the EXACT contract all agents must use
to interact with the DeFi protocol.

This is the "Adapter Interface" in the Adapter Pattern. The real smart-contract
implementation and the MockDeFiProtocol both inherit from this class, so agents
are completely decoupled from the underlying blockchain state.

No agent should ever import MockDeFiProtocol directly.
"""

from abc import ABC, abstractmethod
from typing import Dict, List


class DeFiProtocolInterface(ABC):
    """
    Abstract interface for a simplified DeFi protocol that combines:
      - An Automated Market Maker (AMM) for token swaps
      - A lending/borrowing module with health factors

    All methods are pure interface definitions — no implementation here.
    """

    # ------------------------------------------------------------------ #
    # READ-ONLY STATE QUERIES                                              #
    # ------------------------------------------------------------------ #

    @abstractmethod
    def get_token_price(self) -> float:
        """
        Returns the current AMM-derived price of ETH in USDC.

        Formula (constant-product AMM):
            price = reserve_usdc / reserve_eth

        Returns:
            float: Price of 1 ETH in USDC units.
        """
        ...

    @abstractmethod
    def get_oracle_price(self) -> float:
        """
        Returns the current external oracle price of ETH in USDC.
        This is independent of the AMM reserves — it represents the
        'true' market price from an off-chain data source.

        Returns:
            float: Oracle price of 1 ETH in USDC units.
        """
        ...

    @abstractmethod
    def get_pool_liquidity(self) -> Dict[str, float]:
        """
        Returns the current state of the AMM liquidity pool.

        Returns:
            dict: {
                "reserve_usdc": float,   # USDC held in the pool
                "reserve_eth":  float,   # ETH held in the pool
                "k":            float,   # constant product invariant
            }
        """
        ...

    @abstractmethod
    def get_user_health_factor(self, address: str) -> float:
        """
        Returns the collateralisation health factor for a borrower.

        health_factor = (collateral_value_usdc * LTV_ratio) / total_debt_usdc

        A health factor < 1.0 means the position is under-collateralised
        and eligible for liquidation.

        Args:
            address (str): The borrower's unique address string.

        Returns:
            float: Health factor (> 1.0 = safe, < 1.0 = liquidatable).
                   Returns float('inf') if address has no debt.
        """
        ...

    @abstractmethod
    def has_bad_debt(self) -> bool:
        """
        Returns True if any borrower position in the protocol has accrued bad debt.
        Bad debt is defined as: (collateral_eth * oracle_price) < debt_usdc.
        """
        ...

    @abstractmethod
    def get_all_borrower_addresses(self) -> List[str]:
        """
        Returns the list of all known borrower addresses in the protocol.
        The Liquidator agent uses this to scan for unhealthy positions.

        Returns:
            List[str]: List of borrower address strings.
        """
        ...

    # ------------------------------------------------------------------ #
    # STATE-CHANGING ACTIONS                                               #
    # ------------------------------------------------------------------ #

    @abstractmethod
    def execute_swap(
        self,
        token_in: str,
        amount_in: float,
        caller_address: str,
    ) -> Dict[str, float]:
        """
        Executes a token swap through the AMM.

        Uses constant-product formula: (x + Δx)(y - Δy) = k
        so Δy = (y * Δx) / (x + Δx)

        Args:
            token_in      (str):   "USDC" or "ETH" — the token being sold.
            amount_in     (float): Amount of token_in to sell.
            caller_address(str):   Address executing the swap (for logging).

        Returns:
            dict: {
                "amount_out":    float,   # tokens received
                "new_price":     float,   # AMM price after the swap
                "price_impact":  float,   # % price change caused by this swap
            }
        """
        ...

    @abstractmethod
    def execute_liquidation(
        self,
        borrower_address: str,
        liquidator_address: str,
    ) -> Dict[str, float]:
        """
        Liquidates an under-collateralised borrower position.

        The liquidator repays the borrower's debt in exchange for a
        liquidation bonus (usually 5–10% of the collateral).

        Args:
            borrower_address   (str): The address to liquidate.
            liquidator_address (str): The address performing the liquidation.

        Returns:
            dict: {
                "debt_repaid":          float,
                "collateral_seized":    float,
                "liquidation_bonus":    float,
            }
        """
        ...

    @abstractmethod
    def execute_borrow(
        self,
        borrower_address: str,
        amount_usdc: float,
    ) -> Dict[str, float]:
        """
        Borrows USDC against the caller's existing ETH collateral.

        Args:
            borrower_address (str):   The address taking the loan.
            amount_usdc      (float): Amount of USDC to borrow.

        Returns:
            dict: {
                "borrowed_amount":  float,
                "new_health_factor": float,   # updated health factor post-borrow
            }
        """
        ...

    @abstractmethod
    def execute_deposit_collateral(
        self,
        borrower_address: str,
        amount_eth: float,
    ) -> Dict[str, float]:
        """
        Deposits ETH collateral into the protocol.

        Args:
            borrower_address (str):   The address depositing collateral.
            amount_eth       (float): Amount of ETH to deposit.

        Returns:
            dict: {
                "deposited_amount":  float,
                "new_health_factor": float,
            }
        """
        ...

    @abstractmethod
    def execute_withdraw_collateral(
        self,
        borrower_address: str,
        amount_eth: float,
    ) -> Dict[str, float]:
        """
        Withdraws ETH collateral from the protocol, ensuring health factor remains >= 1.0.

        Args:
            borrower_address (str):   The address withdrawing collateral.
            amount_eth       (float): Amount of ETH to withdraw.

        Returns:
            dict: {
                "withdrawn_amount":  float,
                "new_health_factor": float,
            }
        """
        ...

    @abstractmethod
    def execute_repay(
        self,
        borrower_address: str,
        amount_usdc: float,
    ) -> Dict[str, float]:
        """
        Repays USDC debt for a borrower.

        Args:
            borrower_address (str):   The address repaying debt.
            amount_usdc      (float): Amount of USDC to repay.

        Returns:
            dict: {
                "repaid_amount":     float,
                "new_health_factor": float,
            }
        """
        ...

    @abstractmethod
    def execute_supply(
        self,
        supplier_address: str,
        token: str,
        amount: float,
    ) -> Dict[str, float]:
        """
        Supplies liquidity to the protocol (adds to reserves).

        Args:
            supplier_address (str):   The address supplying liquidity.
            token            (str):   "USDC" or "ETH".
            amount           (float): Amount to supply.

        Returns:
            dict: {
                "lp_tokens_minted": float,   # LP share tokens received
                "new_reserve":      float,   # updated reserve for that token
            }
        """
        ...

    @abstractmethod
    def execute_withdraw(
        self,
        withdrawer_address: str,
        fraction: float,
    ) -> Dict[str, float]:
        """
        Withdraws liquidity from the protocol equivalent to the fraction of total pool.

        Args:
            withdrawer_address (str): The address withdrawing liquidity.
            fraction           (float): Fraction to withdraw (0.0 to 1.0)

        Returns:
            dict: {
                "usdc_withdrawn": float,
                "eth_withdrawn": float,
            }
        """
        ...

    @abstractmethod
    def advance_oracle_price(self) -> float:
        """
        Advances the oracle price by one time step (random walk).
        Called once per model step BEFORE agents act.

        Returns:
            float: New oracle price after the step.
        """
        ...