drift/utils/glassnode/mining.py

from .utils import *


class Mining:
    """
    Mining class.

    Methods
    -------
    __init__(glassnode_client):
        Constructs a Mining object.
    difficulty():
        Returns difficulty to mine a block.
    hash_rate():
        Returns hash rate.
    miner_revenue_total():
        Returns the total miner revenue.
    miner_revenue_fees():
        Returns the percentage of miner revenue derived from fees.
    miner_revenue_block_rewards():
        Returns the total amount of newly minted coins.
    miner_outflow_multiple():
        Returns the miner outflow multiple.
    thermocap():
        Returns Thermocap data.
    market_cap_to_thermocap_ratio():
        Returns the Marketcap to Thermocap Ratio.
    miner_unspent_supply():
        Returns unspent miner supply.
    miner_names():
        Returns miner names for a mining endpoint.
    """

    def __init__(self, glassnode_client):
        self._gc = glassnode_client

    def difficulty(self) -> pd.DataFrame:
        """
        The current estimated number of hashes required to mine a block. Values are denoted in raw hashes.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.DifficultyLatest>`_

        :return: A DataFrame with the latest difficulty data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/difficulty_latest"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def hash_rate(self) -> pd.DataFrame:
        """
        The average estimated number of hashes per second produced by the miners in the network.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.HashRateMean>`_

        :return: A DataFrame with hash rate data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/hash_rate_mean"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def miner_revenue_total(self, miner=None) -> pd.DataFrame:
        """
        The total miner revenue, i.e. fees plus newly minted coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.RevenueSum>`_

        :return: A DataFrame with total revenue data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/revenue_sum"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint, {"m": miner}))

    def miner_revenue_fees(self) -> pd.DataFrame:
        """
        The percentage of miner revenue derived from fees, i.e. fees divided by fees plus minted coins.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.RevenueFromFees>`_

        :return: A DataFrame with revenue fees data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/revenue_from_fees"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def miner_revenue_block_rewards(self, miner=None) -> pd.DataFrame:
        """
        The total amount of newly minted coins, i.e. block rewards.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.VolumeMinedSum>`_

        :return: A DataFrame with revenue block rewards data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/volume_mined_sum"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint, {"m": miner}))

    def miner_outflow_multiple(self, miner=None) -> pd.DataFrame:
        """
        The Miner Outflow Multiple indicates periods where the amount of bitcoins flowing out of
        miner addresses is high with respect to its historical average.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.MinersOutflowMultiple>`_

        :return: A DataFrame MOM data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/miners_outflow_multiple"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint, {"m": miner}))

    def thermocap(self) -> pd.DataFrame:
        """
        "Thermocap" is the aggregated amount of coins paid to miners and serves as a proxy to mining resources spent.
        It serves a measure of the true capital flow into Bitcoin.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.Thermocap>`_

        :return: A DataFrame with thermocap data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/thermocap"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def market_cap_to_thermocap_ratio(self) -> pd.DataFrame:
        """
        The Marketcap to Thermocap Ratio can be used to assess if the asset's price is currently trading
        at a premium with respect to total security spend by miners.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.MarketcapThermocapRatio>`_

        :return: A DataFrame with M/T ratio data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/marketcap_thermocap_ratio"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def miner_unspent_supply(self) -> pd.DataFrame:
        """
        The total mount of coins in coinbase transactions that have never been moved.
        `View in Studio <https://studio.glassnode.com/metrics?a=BTC&m=mining.MinersUnspentSupply>`_

        :return: A DataFrame with unspent miner supply data.
        :rtype: DataFrame
        """
        endpoint = "/v1/metrics/mining/miners_unspent_supply"
        if not is_supported_by_endpoint(self._gc, endpoint):
            return pd.DataFrame()

        return response_to_dataframe(self._gc.get(endpoint))

    def miner_names(self, endpoint="revenue_sum") -> list:
        """
        Returns a list of miner names for a mining endpoint.

        :param endpoint: Available endpoints: revenue_sum, volume_mined_sum, miners_outflow_multiple
        :return: A List with miner names.
        :rtype: List
        """
        miners = self._gc.get(f"/v1/metrics/mining/{endpoint}/miners")
        return miners[self._gc.asset]