Module project.eods.beacon_chain_accounting

This module modifies the state of the beacon chain accounting protocol gadget.

Classes

class BeaconChainAccounting
Expand source code
class BeaconChainAccounting:
    """
    This class is responsible for exposing the balance sheet operations - deposit, delegation and withdrawal.
    
    These are the different contexts of depositing/withdrawing:
        deposit_to_delegate_contract -> delegator balance : deposit_to_delegator_balance
        ExecutionAddress <- delegator balance : withdraw_from_delegator_balance
        delegator balance -> validator : delegate_to_validator
        delegator balance <- validator : withdraw_from_validator
    """
    
    delegators_registry: DelegatorsRegistry
    validators_registry: ValidatorsRegistry
    delegated_validators_registry: DelegatedValidatorsRegistry

    def __init__(self):
        self.delegators_registry = DelegatorsRegistry()
        self.validators_registry = ValidatorsRegistry()
        self.delegated_validators_registry = DelegatedValidatorsRegistry()

    def delegate_to_validator(self, delegator_index: DelegatorIndex, validator_pubkey: BLSPubkey, amount: Gwei):
        """
        This method acts as an entrypoint for delegation. It creates a delegated validator if needed and 
        it funds it with a given amount.
        
        Args:
            delegator_index (DelegatorIndex): The index of the delegator.
            validator_pubkey (BLSPubkey): The public key of the validator.
            amount (Gwei): The amount delegated, with added underflow protection
        """
        if amount > self.delegators_registry.delegators_balances[delegator_index]:
            amount = self.delegators_registry.delegators_balances[delegator_index]

        self.delegators_registry.decrease_delegator_balance(delegator_index, amount)
        
        validator = self.validators_registry.get_validator_by_id(validator_pubkey)

        if not self.delegated_validators_registry.is_validator_delegated(validator.pubkey):
            self.delegated_validators_registry.create_delegated_validator(validator, amount)

        self.delegated_validators_registry.process_delegation(delegator_index, validator.pubkey, amount)

    def deposit_to_delegator_balance(self, pubkey: BLSPubkey, amount: Gwei):
        """
        This method will deposit an amount to a delegator's balance.
        If there is no delegator the registry will create one.
        """
        self.delegators_registry.deposit(pubkey, amount)
         
    def withdraw_from_delegator_balance(self, pubkey: BLSPubkey, amount: Gwei):
        """
        This method facilitates withdrawal from a delegator's balance.
        """
        self.delegators_registry.withdraw(pubkey, amount)

    def withdraw_from_validator(self, delegator_index: DelegatorIndex, validator_pubkey: BLSPubkey, amount: Gwei):
        """
        This method acts as an entrypoint for withdrawal from a validator. 
        Args:
            delegator_index (DelegatorIndex): The index of the delegator.
            validator_pubkey (BLSPubkey): The public key of the validator.
            amount (Gwei): The amount that whould be withdrawn.
        """
        
        validator = self.validators_registry.get_validator_by_id(validator_pubkey)

        if amount < 0:
            raise ValueError("Withdrawal amount must be positive")

        if not self.delegated_validators_registry.is_validator_delegated(validator.pubkey):
            raise ValueError("Validator with the provided pubkey is not delegated validator")

        withdrawal_amount = self.delegated_validators_registry.process_withdrawal(delegator_index, validator.pubkey, amount)

        self.delegators_registry.increase_delegator_balance(delegator_index, withdrawal_amount)

This class is responsible for exposing the balance sheet operations - deposit, delegation and withdrawal.

These are the different contexts of depositing/withdrawing: deposit_to_delegate_contract -> delegator balance : deposit_to_delegator_balance ExecutionAddress <- delegator balance : withdraw_from_delegator_balance delegator balance -> validator : delegate_to_validator delegator balance <- validator : withdraw_from_validator

Class variables

var delegated_validators_registry : eods.delegated_validators_registry.DelegatedValidatorsRegistry
var delegators_registry : eods.delegators_registry.DelegatorsRegistry
var validators_registry : protocol.validators_registry.ValidatorsRegistry

Methods

def delegate_to_validator(self,
delegator_index: numpy.uint64,
validator_pubkey: ByteString,
amount: numpy.uint64)
Expand source code
def delegate_to_validator(self, delegator_index: DelegatorIndex, validator_pubkey: BLSPubkey, amount: Gwei):
    """
    This method acts as an entrypoint for delegation. It creates a delegated validator if needed and 
    it funds it with a given amount.
    
    Args:
        delegator_index (DelegatorIndex): The index of the delegator.
        validator_pubkey (BLSPubkey): The public key of the validator.
        amount (Gwei): The amount delegated, with added underflow protection
    """
    if amount > self.delegators_registry.delegators_balances[delegator_index]:
        amount = self.delegators_registry.delegators_balances[delegator_index]

    self.delegators_registry.decrease_delegator_balance(delegator_index, amount)
    
    validator = self.validators_registry.get_validator_by_id(validator_pubkey)

    if not self.delegated_validators_registry.is_validator_delegated(validator.pubkey):
        self.delegated_validators_registry.create_delegated_validator(validator, amount)

    self.delegated_validators_registry.process_delegation(delegator_index, validator.pubkey, amount)

This method acts as an entrypoint for delegation. It creates a delegated validator if needed and it funds it with a given amount.

Args

delegator_index : DelegatorIndex
The index of the delegator.
validator_pubkey : BLSPubkey
The public key of the validator.
amount : Gwei
The amount delegated, with added underflow protection
def deposit_to_delegator_balance(self, pubkey: ByteString, amount: numpy.uint64)
Expand source code
def deposit_to_delegator_balance(self, pubkey: BLSPubkey, amount: Gwei):
    """
    This method will deposit an amount to a delegator's balance.
    If there is no delegator the registry will create one.
    """
    self.delegators_registry.deposit(pubkey, amount)

This method will deposit an amount to a delegator's balance. If there is no delegator the registry will create one.

def withdraw_from_delegator_balance(self, pubkey: ByteString, amount: numpy.uint64)
Expand source code
def withdraw_from_delegator_balance(self, pubkey: BLSPubkey, amount: Gwei):
    """
    This method facilitates withdrawal from a delegator's balance.
    """
    self.delegators_registry.withdraw(pubkey, amount)

This method facilitates withdrawal from a delegator's balance.

def withdraw_from_validator(self,
delegator_index: numpy.uint64,
validator_pubkey: ByteString,
amount: numpy.uint64)
Expand source code
def withdraw_from_validator(self, delegator_index: DelegatorIndex, validator_pubkey: BLSPubkey, amount: Gwei):
    """
    This method acts as an entrypoint for withdrawal from a validator. 
    Args:
        delegator_index (DelegatorIndex): The index of the delegator.
        validator_pubkey (BLSPubkey): The public key of the validator.
        amount (Gwei): The amount that whould be withdrawn.
    """
    
    validator = self.validators_registry.get_validator_by_id(validator_pubkey)

    if amount < 0:
        raise ValueError("Withdrawal amount must be positive")

    if not self.delegated_validators_registry.is_validator_delegated(validator.pubkey):
        raise ValueError("Validator with the provided pubkey is not delegated validator")

    withdrawal_amount = self.delegated_validators_registry.process_withdrawal(delegator_index, validator.pubkey, amount)

    self.delegators_registry.increase_delegator_balance(delegator_index, withdrawal_amount)

This method acts as an entrypoint for withdrawal from a validator.

Args

delegator_index : DelegatorIndex
The index of the delegator.
validator_pubkey : BLSPubkey
The public key of the validator.
amount : Gwei
The amount that whould be withdrawn.