Module model.state_variables

Definition of State Variables, their types, and default values.

By using a dataclass to represent the State Variables: * We can use types for Python type hints * Set default values * Ensure that all State Variables are initialized

Expand source code
"""
Definition of State Variables, their types, and default values.

By using a dataclass to represent the State Variables:
* We can use types for Python type hints
* Set default values
* Ensure that all State Variables are initialized
"""


import numpy as np
from dataclasses import dataclass
from datetime import datetime

import model.constants as constants
import data.api.beaconchain as beaconchain
import data.api.etherscan as etherscan
from model.system_parameters import validator_environments
from model.types import (
    Gwei,
    Gwei_per_Gas,
    ETH,
    USD,
    USD_per_ETH,
    Percentage,
    Stage,
)
from data.historical_values import eth_price_mean, eth_price_min, eth_price_max


# Get number of validator environments for initializing Numpy array size
number_of_validator_environments = len(validator_environments)

# Intial state from external live data source, setting a default in case API call fails
number_of_validators: int = beaconchain.get_validators_count(default=156_250)
eth_staked: ETH = (
    beaconchain.get_total_validator_balance(default=5_000_000e9) / constants.gwei
)
eth_supply: ETH = etherscan.get_eth_supply(default=116_250_000e18) / constants.wei


@dataclass
class StateVariables:
    """State Variables
    Each State Variable is defined as:
    state variable key: state variable type = default state variable value
    """

    # Time state variables
    stage: Stage = None
    """
    The stage of the network upgrade process.

    By default set to PROOF_OF_STAKE Stage, where EIP1559 is enabled and POW issuance is disabled.

    Otherwise set to ALL Stage, which transitions through each stage, updating the `stage` State Variable.

    See model.types.Stage Enum for further documentation.
    """
    timestamp: datetime = None
    """
    The timestamp for each timestep as a Python `datetime` object, starting from `date_start` Parameter.
    """

    # Ethereum state variables
    eth_price: USD_per_ETH = eth_price_mean
    """The ETH spot price"""
    eth_supply: ETH = eth_supply
    """The total ETH supply"""
    eth_staked: ETH = eth_staked
    """The total ETH staked as part of the Proof of Stake system"""
    supply_inflation: Percentage = 0
    """The annualized ETH supply inflation rate"""
    network_issuance: ETH = 0
    """The total network issuance in ETH"""
    pow_issuance: ETH = 0
    """The total Proof of Work issuance in ETH"""

    # Validator state variables
    number_of_validators_in_activation_queue: int = 0
    """The number of validators in activation queue"""
    average_effective_balance: Gwei = 32 * constants.gwei
    """The validator average effective balance"""
    number_of_validators: int = number_of_validators
    """The total number of validators"""
    number_of_validators_online: int = 0
    """The total number of online validators"""
    number_of_validators_offline: int = 0
    """The total number of offline validators"""

    # Reward and penalty state variables
    base_reward: Gwei = 0
    """
    Validator rewards and penalties are calculated in terms of the base reward.
    Under perfect network conditions, each validator should receive 1 base reward per epoch for performing their duties.
    """
    validating_rewards: Gwei = 0
    """The total rewards received for PoS validation (attestation, block proposal, sync vote)"""
    validating_penalties: Gwei = 0
    """The total penalties received for failing to perform PoS validation duties (attestation, sync vote)"""
    source_reward: Gwei = 0
    """The total rewards received for getting a source vote in time and correctly"""
    target_reward: Gwei = 0
    """The total rewards received for getting a target vote in time and correctly"""
    head_reward: Gwei = 0
    """The total rewards received for getting a head vote in time and correctly"""
    block_proposer_reward: Gwei = 0
    """The total rewards received for successfully proposing a block"""
    sync_reward: Gwei = 0
    """The total rewards received for attesting as part of a sync committee"""
    attestation_penalties: Gwei = 0
    """The total penalties received for failing to perform attestation duties"""
    sync_committee_penalties: Gwei = 0
    """The total penalties received for failing to perform sync committee duties"""

    # Slashing state variables
    amount_slashed: Gwei = 0
    """The total penalties applied for slashable offences"""
    whistleblower_rewards: Gwei = 0
    """The total rewards received as a proportion of the effective balance of the slashed validators"""

    # EIP1559 state variables
    base_fee_per_gas: Gwei_per_Gas = 1
    """The base fee burned, in Gwei per gas, dynamically updated for each block"""
    total_base_fee: Gwei = 0
    """The total base fee burned for all transactions included in blockspace"""
    total_priority_fee_to_miners: Gwei = 0
    """"The total priority fee to miners pre-merge for all transactions included in blockspace"""
    total_priority_fee_to_validators: Gwei = 0
    """"The total priority fee to validators post-merge for all transactions included in blockspace"""

    # System metric state variables
    validator_eth_staked: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The ETH staked per validator environment"""
    validator_revenue: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total revenue (income received) for performing PoS duties per validator environment"""
    validator_profit: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total profit (income received - costs) per validator environment"""
    validator_revenue_yields: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total annualized revenue (income received) yields (percentage of investment amount)
    per validator environment"""
    validator_profit_yields: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total annualized profit (income received - costs) yields (percentage of investment amount)
    per validator environment"""

    validator_count_distribution: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total number of validators per validator environment"""
    validator_hardware_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator hardware operation costs per validator environment"""
    validator_cloud_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator cloud operation costs per validator environment"""
    validator_third_party_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator third-party fee costs validator environment"""
    validator_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator costs validator environment"""

    total_online_validator_rewards: Gwei = 0
    """The total rewards received by online validators"""
    total_network_costs: USD = 0
    """The total validator operational costs for securing the network"""
    total_revenue: USD = 0
    """The total validator revenue (income received)"""
    total_profit: USD = 0
    """The total validator profit (income received - costs)"""
    total_revenue_yields: Percentage = 0
    """Annualized revenue (income received) for all validators"""
    total_profit_yields: Percentage = 0
    """Annualized profit (income received - costs) for all validators"""


# Initialize State Variables instance with default values
initial_state = StateVariables().__dict__

Classes

class StateVariables (stage: Stage = None, timestamp: datetime.datetime = None, eth_price: float = 1251.477131147541, eth_supply: float = 116678363.1865, eth_staked: float = 6314465.175230042, supply_inflation: float = 0, network_issuance: float = 0, pow_issuance: float = 0, number_of_validators_in_activation_queue: int = 0, average_effective_balance: float = 32000000000.0, number_of_validators: int = 191596, number_of_validators_online: int = 0, number_of_validators_offline: int = 0, base_reward: float = 0, validating_rewards: float = 0, validating_penalties: float = 0, source_reward: float = 0, target_reward: float = 0, head_reward: float = 0, block_proposer_reward: float = 0, sync_reward: float = 0, attestation_penalties: float = 0, sync_committee_penalties: float = 0, amount_slashed: float = 0, whistleblower_rewards: float = 0, base_fee_per_gas: float = 1, total_base_fee: float = 0, total_priority_fee_to_miners: float = 0, total_priority_fee_to_validators: float = 0, validator_eth_staked: numpy.ndarray = array([[0], [0], [0], [0], [0], [0], [0]]), validator_revenue: numpy.ndarray = array([[0], [0], [0], [0], [0], [0], [0]]), validator_profit: numpy.ndarray = array([[0], [0], [0], [0], [0], [0], [0]]), validator_revenue_yields: numpy.ndarray = array([[0], [0], [0], [0], [0], [0], [0]]), validator_profit_yields: numpy.ndarray = array([[0], [0], [0], [0], [0], [0], [0]]), validator_count_distribution: numpy.ndarray = array([[0], [0], [0], [0], [0], [0], [0]]), validator_hardware_costs: numpy.ndarray = array([[0.], [0.], [0.], [0.], [0.], [0.], [0.]]), validator_cloud_costs: numpy.ndarray = array([[0.], [0.], [0.], [0.], [0.], [0.], [0.]]), validator_third_party_costs: numpy.ndarray = array([[0.], [0.], [0.], [0.], [0.], [0.], [0.]]), validator_costs: numpy.ndarray = array([[0.], [0.], [0.], [0.], [0.], [0.], [0.]]), total_online_validator_rewards: float = 0, total_network_costs: float = 0, total_revenue: float = 0, total_profit: float = 0, total_revenue_yields: float = 0, total_profit_yields: float = 0)

State Variables Each State Variable is defined as: state variable key: state variable type = default state variable value

Expand source code
class StateVariables:
    """State Variables
    Each State Variable is defined as:
    state variable key: state variable type = default state variable value
    """

    # Time state variables
    stage: Stage = None
    """
    The stage of the network upgrade process.

    By default set to PROOF_OF_STAKE Stage, where EIP1559 is enabled and POW issuance is disabled.

    Otherwise set to ALL Stage, which transitions through each stage, updating the `stage` State Variable.

    See model.types.Stage Enum for further documentation.
    """
    timestamp: datetime = None
    """
    The timestamp for each timestep as a Python `datetime` object, starting from `date_start` Parameter.
    """

    # Ethereum state variables
    eth_price: USD_per_ETH = eth_price_mean
    """The ETH spot price"""
    eth_supply: ETH = eth_supply
    """The total ETH supply"""
    eth_staked: ETH = eth_staked
    """The total ETH staked as part of the Proof of Stake system"""
    supply_inflation: Percentage = 0
    """The annualized ETH supply inflation rate"""
    network_issuance: ETH = 0
    """The total network issuance in ETH"""
    pow_issuance: ETH = 0
    """The total Proof of Work issuance in ETH"""

    # Validator state variables
    number_of_validators_in_activation_queue: int = 0
    """The number of validators in activation queue"""
    average_effective_balance: Gwei = 32 * constants.gwei
    """The validator average effective balance"""
    number_of_validators: int = number_of_validators
    """The total number of validators"""
    number_of_validators_online: int = 0
    """The total number of online validators"""
    number_of_validators_offline: int = 0
    """The total number of offline validators"""

    # Reward and penalty state variables
    base_reward: Gwei = 0
    """
    Validator rewards and penalties are calculated in terms of the base reward.
    Under perfect network conditions, each validator should receive 1 base reward per epoch for performing their duties.
    """
    validating_rewards: Gwei = 0
    """The total rewards received for PoS validation (attestation, block proposal, sync vote)"""
    validating_penalties: Gwei = 0
    """The total penalties received for failing to perform PoS validation duties (attestation, sync vote)"""
    source_reward: Gwei = 0
    """The total rewards received for getting a source vote in time and correctly"""
    target_reward: Gwei = 0
    """The total rewards received for getting a target vote in time and correctly"""
    head_reward: Gwei = 0
    """The total rewards received for getting a head vote in time and correctly"""
    block_proposer_reward: Gwei = 0
    """The total rewards received for successfully proposing a block"""
    sync_reward: Gwei = 0
    """The total rewards received for attesting as part of a sync committee"""
    attestation_penalties: Gwei = 0
    """The total penalties received for failing to perform attestation duties"""
    sync_committee_penalties: Gwei = 0
    """The total penalties received for failing to perform sync committee duties"""

    # Slashing state variables
    amount_slashed: Gwei = 0
    """The total penalties applied for slashable offences"""
    whistleblower_rewards: Gwei = 0
    """The total rewards received as a proportion of the effective balance of the slashed validators"""

    # EIP1559 state variables
    base_fee_per_gas: Gwei_per_Gas = 1
    """The base fee burned, in Gwei per gas, dynamically updated for each block"""
    total_base_fee: Gwei = 0
    """The total base fee burned for all transactions included in blockspace"""
    total_priority_fee_to_miners: Gwei = 0
    """"The total priority fee to miners pre-merge for all transactions included in blockspace"""
    total_priority_fee_to_validators: Gwei = 0
    """"The total priority fee to validators post-merge for all transactions included in blockspace"""

    # System metric state variables
    validator_eth_staked: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The ETH staked per validator environment"""
    validator_revenue: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total revenue (income received) for performing PoS duties per validator environment"""
    validator_profit: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total profit (income received - costs) per validator environment"""
    validator_revenue_yields: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total annualized revenue (income received) yields (percentage of investment amount)
    per validator environment"""
    validator_profit_yields: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total annualized profit (income received - costs) yields (percentage of investment amount)
    per validator environment"""

    validator_count_distribution: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=int
    )
    """The total number of validators per validator environment"""
    validator_hardware_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator hardware operation costs per validator environment"""
    validator_cloud_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator cloud operation costs per validator environment"""
    validator_third_party_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator third-party fee costs validator environment"""
    validator_costs: np.ndarray = np.zeros(
        (number_of_validator_environments, 1), dtype=USD
    )
    """The total validator costs validator environment"""

    total_online_validator_rewards: Gwei = 0
    """The total rewards received by online validators"""
    total_network_costs: USD = 0
    """The total validator operational costs for securing the network"""
    total_revenue: USD = 0
    """The total validator revenue (income received)"""
    total_profit: USD = 0
    """The total validator profit (income received - costs)"""
    total_revenue_yields: Percentage = 0
    """Annualized revenue (income received) for all validators"""
    total_profit_yields: Percentage = 0
    """Annualized profit (income received - costs) for all validators"""

Class variables

var amount_slashed : float

The total penalties applied for slashable offences

var attestation_penalties : float

The total penalties received for failing to perform attestation duties

var average_effective_balance : float

The validator average effective balance

var base_fee_per_gas : float

The base fee burned, in Gwei per gas, dynamically updated for each block

var base_reward : float

Validator rewards and penalties are calculated in terms of the base reward. Under perfect network conditions, each validator should receive 1 base reward per epoch for performing their duties.

var block_proposer_reward : float

The total rewards received for successfully proposing a block

var eth_price : float

The ETH spot price

var eth_staked : float

The total ETH staked as part of the Proof of Stake system

var eth_supply : float

The total ETH supply

var head_reward : float

The total rewards received for getting a head vote in time and correctly

var network_issuance : float

The total network issuance in ETH

var number_of_validators : int

The total number of validators

var number_of_validators_in_activation_queue : int

The number of validators in activation queue

var number_of_validators_offline : int

The total number of offline validators

var number_of_validators_online : int

The total number of online validators

var pow_issuance : float

The total Proof of Work issuance in ETH

var source_reward : float

The total rewards received for getting a source vote in time and correctly

var stageStage

The stage of the network upgrade process.

By default set to PROOF_OF_STAKE Stage, where EIP1559 is enabled and POW issuance is disabled.

Otherwise set to ALL Stage, which transitions through each stage, updating the stage State Variable.

See model.types.Stage Enum for further documentation.

var supply_inflation : float

The annualized ETH supply inflation rate

var sync_committee_penalties : float

The total penalties received for failing to perform sync committee duties

var sync_reward : float

The total rewards received for attesting as part of a sync committee

var target_reward : float

The total rewards received for getting a target vote in time and correctly

var timestamp : datetime.datetime

The timestamp for each timestep as a Python datetime object, starting from date_start Parameter.

var total_base_fee : float

The total base fee burned for all transactions included in blockspace

var total_network_costs : float

The total validator operational costs for securing the network

var total_online_validator_rewards : float

The total rewards received by online validators

var total_priority_fee_to_miners : float

"The total priority fee to miners pre-merge for all transactions included in blockspace

var total_priority_fee_to_validators : float

"The total priority fee to validators post-merge for all transactions included in blockspace

var total_profit : float

The total validator profit (income received - costs)

var total_profit_yields : float

Annualized profit (income received - costs) for all validators

var total_revenue : float

The total validator revenue (income received)

var total_revenue_yields : float

Annualized revenue (income received) for all validators

var validating_penalties : float

The total penalties received for failing to perform PoS validation duties (attestation, sync vote)

var validating_rewards : float

The total rewards received for PoS validation (attestation, block proposal, sync vote)

var validator_cloud_costs : numpy.ndarray

The total validator cloud operation costs per validator environment

var validator_costs : numpy.ndarray

The total validator costs validator environment

var validator_count_distribution : numpy.ndarray

The total number of validators per validator environment

var validator_eth_staked : numpy.ndarray

The ETH staked per validator environment

var validator_hardware_costs : numpy.ndarray

The total validator hardware operation costs per validator environment

var validator_profit : numpy.ndarray

The total profit (income received - costs) per validator environment

var validator_profit_yields : numpy.ndarray

The total annualized profit (income received - costs) yields (percentage of investment amount) per validator environment

var validator_revenue : numpy.ndarray

The total revenue (income received) for performing PoS duties per validator environment

var validator_revenue_yields : numpy.ndarray

The total annualized revenue (income received) yields (percentage of investment amount) per validator environment

var validator_third_party_costs : numpy.ndarray

The total validator third-party fee costs validator environment

var whistleblower_rewards : float

The total rewards received as a proportion of the effective balance of the slashed validators