github.com/filecoin-project/specs-actors/v4@v4.0.2/actors/builtin/reward/reward_state.go (about)

     1  package reward
     2  
     3  import (
     4  	"github.com/filecoin-project/go-state-types/abi"
     5  	"github.com/filecoin-project/go-state-types/big"
     6  
     7  	"github.com/filecoin-project/specs-actors/v4/actors/util/smoothing"
     8  )
     9  
    10  // A quantity of space * time (in byte-epochs) representing power committed to the network for some duration.
    11  type Spacetime = big.Int
    12  
    13  // 36.266260308195979333 FIL
    14  // https://www.wolframalpha.com/input/?i=IntegerPart%5B330%2C000%2C000+*+%281+-+Exp%5B-Log%5B2%5D+%2F+%286+*+%281+year+%2F+30+seconds%29%29%5D%29+*+10%5E18%5D
    15  const InitialRewardPositionEstimateStr = "36266260308195979333"
    16  
    17  var InitialRewardPositionEstimate = big.MustFromString(InitialRewardPositionEstimateStr)
    18  
    19  // -1.0982489*10^-7 FIL per epoch.  Change of simple minted tokens between epochs 0 and 1
    20  // https://www.wolframalpha.com/input/?i=IntegerPart%5B%28Exp%5B-Log%5B2%5D+%2F+%286+*+%281+year+%2F+30+seconds%29%29%5D+-+1%29+*+10%5E18%5D
    21  var InitialRewardVelocityEstimate = abi.NewTokenAmount(-109897758509)
    22  
    23  // Changed since v0:
    24  // - ThisEpochRewardSmoothed is not a pointer
    25  type State struct {
    26  	// CumsumBaseline is a target CumsumRealized needs to reach for EffectiveNetworkTime to increase
    27  	// CumsumBaseline and CumsumRealized are expressed in byte-epochs.
    28  	CumsumBaseline Spacetime
    29  
    30  	// CumsumRealized is cumulative sum of network power capped by BaselinePower(epoch)
    31  	CumsumRealized Spacetime
    32  
    33  	// EffectiveNetworkTime is ceiling of real effective network time `theta` based on
    34  	// CumsumBaselinePower(theta) == CumsumRealizedPower
    35  	// Theta captures the notion of how much the network has progressed in its baseline
    36  	// and in advancing network time.
    37  	EffectiveNetworkTime abi.ChainEpoch
    38  
    39  	// EffectiveBaselinePower is the baseline power at the EffectiveNetworkTime epoch
    40  	EffectiveBaselinePower abi.StoragePower
    41  
    42  	// The reward to be paid in per WinCount to block producers.
    43  	// The actual reward total paid out depends on the number of winners in any round.
    44  	// This value is recomputed every non-null epoch and used in the next non-null epoch.
    45  	ThisEpochReward abi.TokenAmount
    46  	// Smoothed ThisEpochReward
    47  	ThisEpochRewardSmoothed smoothing.FilterEstimate
    48  
    49  	// The baseline power the network is targeting at st.Epoch
    50  	ThisEpochBaselinePower abi.StoragePower
    51  
    52  	// Epoch tracks for which epoch the Reward was computed
    53  	Epoch abi.ChainEpoch
    54  
    55  	// TotalStoragePowerReward tracks the total FIL awarded to block miners
    56  	TotalStoragePowerReward abi.TokenAmount
    57  
    58  	// Simple and Baseline totals are constants used for computing rewards.
    59  	// They are on chain because of a historical fix resetting baseline value
    60  	// in a way that depended on the history leading immediately up to the
    61  	// migration fixing the value.  These values can be moved from state back
    62  	// into a code constant in a subsequent upgrade.
    63  	SimpleTotal   abi.TokenAmount
    64  	BaselineTotal abi.TokenAmount
    65  }
    66  
    67  func ConstructState(currRealizedPower abi.StoragePower) *State {
    68  	st := &State{
    69  		CumsumBaseline:         big.Zero(),
    70  		CumsumRealized:         big.Zero(),
    71  		EffectiveNetworkTime:   0,
    72  		EffectiveBaselinePower: BaselineInitialValue,
    73  
    74  		ThisEpochReward:        big.Zero(),
    75  		ThisEpochBaselinePower: InitBaselinePower(),
    76  		Epoch:                  -1,
    77  
    78  		ThisEpochRewardSmoothed: smoothing.NewEstimate(InitialRewardPositionEstimate, InitialRewardVelocityEstimate),
    79  		TotalStoragePowerReward: big.Zero(),
    80  
    81  		SimpleTotal:   DefaultSimpleTotal,
    82  		BaselineTotal: DefaultBaselineTotal,
    83  	}
    84  
    85  	st.updateToNextEpochWithReward(currRealizedPower)
    86  
    87  	return st
    88  }
    89  
    90  // Takes in current realized power and updates internal state
    91  // Used for update of internal state during null rounds
    92  func (st *State) updateToNextEpoch(currRealizedPower abi.StoragePower) {
    93  	st.Epoch++
    94  	st.ThisEpochBaselinePower = BaselinePowerFromPrev(st.ThisEpochBaselinePower)
    95  	cappedRealizedPower := big.Min(st.ThisEpochBaselinePower, currRealizedPower)
    96  	st.CumsumRealized = big.Add(st.CumsumRealized, cappedRealizedPower)
    97  
    98  	for st.CumsumRealized.GreaterThan(st.CumsumBaseline) {
    99  		st.EffectiveNetworkTime++
   100  		st.EffectiveBaselinePower = BaselinePowerFromPrev(st.EffectiveBaselinePower)
   101  		st.CumsumBaseline = big.Add(st.CumsumBaseline, st.EffectiveBaselinePower)
   102  	}
   103  }
   104  
   105  // Takes in a current realized power for a reward epoch and computes
   106  // and updates reward state to track reward for the next epoch
   107  func (st *State) updateToNextEpochWithReward(currRealizedPower abi.StoragePower) {
   108  	prevRewardTheta := ComputeRTheta(st.EffectiveNetworkTime, st.EffectiveBaselinePower, st.CumsumRealized, st.CumsumBaseline)
   109  	st.updateToNextEpoch(currRealizedPower)
   110  	currRewardTheta := ComputeRTheta(st.EffectiveNetworkTime, st.EffectiveBaselinePower, st.CumsumRealized, st.CumsumBaseline)
   111  
   112  	st.ThisEpochReward = computeReward(st.Epoch, prevRewardTheta, currRewardTheta, st.SimpleTotal, st.BaselineTotal)
   113  }
   114  
   115  func (st *State) updateSmoothedEstimates(delta abi.ChainEpoch) {
   116  	filterReward := smoothing.LoadFilter(st.ThisEpochRewardSmoothed, smoothing.DefaultAlpha, smoothing.DefaultBeta)
   117  	st.ThisEpochRewardSmoothed = filterReward.NextEstimate(st.ThisEpochReward, delta)
   118  }