KIP 82: A new GC reward structure due to abolition of the Gini coefficient

from collections import defaultdict

MAGMA_BLOCK_NUMBER = 99841497
KORE_BLOCK_NUMBER = 120000000 # TBD

# Block header. Only relevant fields are shown here.
class Header:
    Number: int = 0   # Block number
    GasUsed: int = 0  # Total gas spent in the block
    BaseFee: int = 0  # Base fee per gas at the block
    RewardBase: string = "" # Reward recipient address of the block proposer

# Network configurations related to reward distribution.
# Corresponds to Klaytn's reward.rewardConfig struct.
class RewardConfig:
    # "istanbul.policy" parameter
    RoundRobin = 0
    Sticky = 1
    WeightedRandom = 2
    ProposerPolicy: int = WeightedRandom

    UnitPrice: int = 25000000000              # "governance.unitprice" parameter (in peb)
    MintingAmount: int = 9600000000000000000  # "reward.mintingamount" parameter (in peb)
    MinimumStake: int = 5000000               # "reward.minimumstake" parameter (in KLAY)
    DeferredTxFee: bool = True                # "reward.deferredtxfee" parameter

    # "reward.ratio" parameter (e.g. "50/40/10")
    CnRatio: int = 50
    KgfRatio: int = 40
    KirRatio: int = 10
    TotalRatio: int = CnRatio + KgfRatio + KirRatio

    # "reward.kip82ratio" parameter (e.g. "20/80") (new)
    CnProposerRatio: int = 20
    CnStakingRatio: int = 80
    CnTotalRatio: int = CnProposerRatio + CnStakingRatio

# CN staking status and KGF/KIR addresses.
# Corresponds to Klaytn's reward.StakingInfo struct.
# Can be obtained from reward.GetStakingInfo(blockNum) function.
class StakingInfo:
    KIRAddr: string = ""
    KGFAddr: string = ""
    Nodes: List[ConsolidatedNode] = []

# Staking information merged under the same CN.
# Sometimes a node would register multiple NodeAddrs
# in which each entry has a different StakingAddr and the same RewardAddr.
# We treat those entries with common RewardAddr as one node.
# Corresponds to Klaytn's reward.ConsolidatedNode struct.
class ConsolidatedNode:
    NodeAddrs: List[string] = []
    StakingAddrs: List[string] = []
    RewardAddr: string = "" # The common reward address of the CN
    StakingAmount: int = 0  # Total staking amount across StakingAddrs (in KLAY)

# Reward distribution details.
class RewardSpec:
    Minted: int = 0   # The amount newly minted
    TotalFee: int = 0 # Total tx fee spent
    BurntFee: int = 0 # The amount burnt
    Proposer: int = 0 # The amount allocated to the block proposer
    Stakers: int = 0  # Total amount allocated to stakers
    Kgf: int = 0      # The amount allocated to KGF
    Kir: int = 0      # The amount allocated to KIR
    Rewards: Dict[string, int] = {}  # Mapping from reward recipient to amounts

# Perform post-transaction state modifications such as block rewards.
# Corresponds to Klaytn's consensus/istanbul/backend.Finalize()
#
# - state is the StateDB to apply the rewards.
# - header is a Header instance.
# - config is a RewardConfig instance.
def finalize_block(state, header, config):
    if config.ProposerPolicy in [RoundRobin, Sticky]:
        spec = calc_deferred_reward_simple(header, config)
    else:
        spec = calc_deferred_reward(header, config)

    for addr, amount in spec.Rewards:
        state.AddBalance(addr, amount)
    header.Root = state.Root()

def calc_deferred_reward_simple(header, config):
    minted = config.MintingAmount

    total_fee = get_total_fee(header)
    if header.Number >= KORE_BLOCK_NUMBER and not config.DeferredTxFee:
        total_fee = 0

    reward_fee = total_fee
    burnt_fee = 0

    if header.Number >= MAGMA_BLOCK_NUMBER:
        burn_amount = get_burn_amount_magma(reward_fee)
        reward_fee -= burn_amount
        burnt_fee += burn_amount

    proposer = minted + reward_fee

    spec = RewardSpec()
    spec.Minted = minted
    spec.TotalFee = total_fee
    spec.BurntFee = burnt_fee
    spec.Proposer = proposer
    spec.Rewards = {header.RewardBase: proposer}
    return spec

# Calculates the deferred rewards, which are determined at the end of block processing.
# Used in reward distribution.
# Returns a RewardSpec.
def calc_deferred_reward(header, config):
    staking_info = GetStakingInfo(header.Number)
    minted = config.MintingAmount
    total_fee, reward_fee, burnt_fee = calc_deferred_fee(header, config)

    proposer, stakers, kgf, kir, split_rem = calc_split(header, config, minted, reward_fee)
    shares, share_rem = calc_shares(config, staking_info, stakers)

    # Remainder from (CN, KGF, KIR) split goes to KGF
    kgf += split_rem
    # Remainder from staker shares goes to Proposer
    proposer += share_rem

    # If KGF or KIR address is not set, proposer gets the portion.
    if staking_info.KGFAddr is None:
        proposer += kgf
        kgf = 0
    if staking_info.KIRAddr is None:
        proposer += kir
        kir = 0

    spec = RewardSpec()
    spec.Minted = minted
    spec.TotalFee = total_fee
    spec.BurntFee = burnt_fee
    spec.Proposer = proposer
    spec.Stakers = stakers
    spec.Kgf = kgf
    spec.Kir = kir

    spec.Rewards = defaultdict(int)
    spec.Rewards[header.RewardBase] += proposer
    if staking_info.KGFAddr is not None:
        spec.Rewards[staking_info.KGFAddr] += kgf
    if staking_info.KIRAddr is not None:
        spec.Rewards[staking_info.KIRAddr] += kir
    for reward_addr, reward_amount in shares:
        spec.Rewards[reward_addr] += reward_amount

    return spec

# Returns (total_fee, reward_fee, burnt_fee)
def calc_deferred_fee(header, config):
    # If not DeferredTxFee, fees are already added to the proposer during TX execution.
    # Therefore, there are no fees to distribute here at the end of block processing.
    # However, the fees must be compensated to calculate actual rewards paid.
    if not config.DeferredTxFee:
        return (0, 0, 0)

    # Start with the total block gas fee
    total_fee = get_total_fee(header)
    reward_fee = total_fee
    burnt_fee = 0

    # Since Magma, burn half of gas
    if header.number >= MAGMA_BLOCK_NUMBER:
        burn_amount = get_burn_amount_magma(reward_fee)
        reward_fee -= burn_amount
        burnt_fee += burn_amount

    # If KIP-82 is enabled, burn fees up to proposer's minted reward
    if header.number >= KORE_BLOCK_NUMBER:
        burn_amount = get_burn_amount_kip82(config, reward_fee)
        reward_fee -= burn_amount
        burnt_fee += burn_amount

    return (total_fee, reward_fee, burnt_fee)

def get_total_fee(header):
    if header.number >= MAGMA_BLOCK_NUMBER:
        return header.GasUsed * header.BaseFee
    else:
        return header.GasUsed * config.UnitPrice

def get_burn_amount_magma(fee):
    return fee / 2

def get_burn_amount_kip82(config, fee):
    cn, _, _ = split_by_ratio(config, config.MintingAmount)
    proposer, _ = split_by_kip82_ratio(config, cn)
    if fee >= proposer:
        return proposer
    else:
        return fee

# Returns (proposer, stakers, kgf, kir, remaining) amounts
# The sum of output must be equal to (minted + reward_fee).
def calc_split(header, config, minted, reward_fee):
    total_resource = minted + reward_fee

    if header.number >= KORE_BLOCK_NUMBER:
        cn, kgf, kir = split_by_ratio(config, minted)
        proposer, stakers = split_by_kip82_ratio(config, cn)
        proposer += reward_fee

        remaining = total_resource - kgf - kir - proposer - stakers
        return (proposer, stakers, kgf, kir, remaining)
    else:
        cn, kgf, kir = split_by_ratio(config, minted + reward_fee)

        remaining = total_resource - kgf - kir - cn
        return (cn, 0, kgf, kir, remaining)

# Split by `ratio`. Ignore remaining amounts.
def split_by_ratio(config, source):
    cn = source * config.CnRatio // config.TotalRatio
    kgf = source * config.KgfRatio // config.TotalRatio
    kir = source * config.KirRatio // config.TotalRatio
    return (cn, kgf, kir)

# Split by `kip82ratio`. Ignore remaining amounts.
def split_by_kip82_ratio(config, source):
    proposer = source * config.CnProposerRatio // config.CnTotalRatio
    stakers = source * config.CnStakingRatio // config.CnTotalRatio
    return (proposer, stakers)

# Distribute stake_reward among staked CNs
# Returns a mapping from each reward address to their reward shares,
# and the remaining amount.
def calc_shares(config, staking_info, stake_reward):
    min_stake = config.MinimumStake
    total_stakes = 0
    for node in staking_info.Nodes:
        if node.StakingAmount > min_stake:
            total_stakes += (node.StakingAmount - min_stake)

    shares = {}
    remaining = stake_reward
    for node in staking_info.Nodes:
        if node.StakingAmount > min_stake:
            effective_stake = node.StakingAmount - min_stake
            reward_amount = stake_reward * effective_stake // total_stakes
            remaining -= reward_amount
            shares[node.RewardAddr] = reward_amount

    return (shares, remaining)