reward

Documentation

Index

• Constants
• Variables
• func BaselinePowerFromPrev(prevEpochBaselinePower abi.StoragePower) abi.StoragePower
• func ComputeRTheta(effectiveNetworkTime abi.ChainEpoch, ...) big.Int
• func InitBaselinePower() abi.StoragePower
• func SlowConvenientBaselineForEpoch(targetEpoch abi.ChainEpoch) abi.StoragePower
• type Actor
  • func (a Actor) AwardBlockReward(rt runtime.Runtime, params *AwardBlockRewardParams) *abi.EmptyValue
  • func (a Actor) Code() cid.Cid
  • func (a Actor) Constructor(rt runtime.Runtime, currRealizedPower *abi.StoragePower) *abi.EmptyValue
  • func (a Actor) Exports() []interface{}
  • func (a Actor) IsSingleton() bool
  • func (a Actor) State() cbor.Er
  • func (a Actor) ThisEpochReward(rt runtime.Runtime, _ *abi.EmptyValue) *ThisEpochRewardReturn
  • func (a Actor) UpdateNetworkKPI(rt runtime.Runtime, currRealizedPower *abi.StoragePower) *abi.EmptyValue
• type AwardBlockRewardParams
• type Spacetime
• type State
  • func ConstructState(currRealizedPower abi.StoragePower) *State
  • func (t *State) MarshalCBOR(w io.Writer) error
  • func (t *State) UnmarshalCBOR(r io.Reader) error
• type StateSummary
  • func CheckStateInvariants(st *State, store adt.Store, priorEpoch abi.ChainEpoch, balance abi.TokenAmount) (*StateSummary, *builtin.MessageAccumulator)
• type ThisEpochRewardReturn

Constants

const InitialRewardPositionEstimateStr = "36266260308195979333"

36.266260308195979333 FIL 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

const PenaltyMultiplier = 3

PenaltyMultiplier is the factor miner penaltys are scaled up by

Variables

var (
	// lambda = ln(2) / (6 * epochsInYear)
	// for Q.128: int(lambda * 2^128)
	// Calculation here: https://www.wolframalpha.com/input/?i=IntegerPart%5BLog%5B2%5D+%2F+%286+*+%281+year+%2F+30+seconds%29%29+*+2%5E128%5D
	Lambda = big.MustFromString("37396271439864487274534522888786")
	// expLamSubOne = e^lambda - 1
	// for Q.128: int(expLamSubOne * 2^128)
	// Calculation here: https://www.wolframalpha.com/input/?i=IntegerPart%5B%5BExp%5BLog%5B2%5D+%2F+%286+*+%281+year+%2F+30+seconds%29%29%5D+-+1%5D+*+2%5E128%5D
	ExpLamSubOne = big.MustFromString("37396273494747879394193016954629")
)

var BaselineExponent = big.MustFromString("340282591298641078465964189926313473653") // Q.128

Floor(e^(ln[1 + 100%] / epochsInYear) * 2^128 Q.128 formatted number such that f(epoch) = baseExponent^epoch grows 100% in one year of epochs Calculation here: https://www.wolframalpha.com/input/?i=IntegerPart%5BExp%5BLog%5B1%2B100%25%5D%2F%28%28365+days%29%2F%2830+seconds%29%29%5D*2%5E128%5D

var BaselineInitialValue = big.NewInt(2_888_888_880_000_000_000) // Q.0

2.5057116798121726 EiB

var DefaultBaselineTotal = big.Mul(big.NewInt(770e6), big.NewInt(1e18)) // 770M

var DefaultSimpleTotal = big.Mul(big.NewInt(330e6), big.NewInt(1e18)) // 330M

These numbers are estimates of the onchain constants. They are good for initializing state in devnets and testing but will not match the on chain values exactly which depend on storage onboarding and upgrade epoch history. They are in units of attoFIL, 10^-18 FIL

var FIL = big.NewInt(1e18)

var InitialRewardPositionEstimate = big.MustFromString(InitialRewardPositionEstimateStr)

var InitialRewardVelocityEstimate = abi.NewTokenAmount(-109897758509)

-1.0982489*10^-7 FIL per epoch. Change of simple minted tokens between epochs 0 and 1 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

var StorageMiningAllocationCheck = big.Mul(big.NewInt(1_100_000_000), FIL)

Functions

func BaselinePowerFromPrev

func BaselinePowerFromPrev(prevEpochBaselinePower abi.StoragePower) abi.StoragePower

Compute BaselinePower(t) from BaselinePower(t-1) with an additional multiplication of the base exponent.

func ComputeRTheta

func ComputeRTheta(effectiveNetworkTime abi.ChainEpoch, baselinePowerAtEffectiveNetworkTime, cumsumRealized, cumsumBaseline big.Int) big.Int

Computes RewardTheta which is is precise fractional value of effectiveNetworkTime. The effectiveNetworkTime is defined by CumsumBaselinePower(theta) == CumsumRealizedPower As baseline power is defined over integers and the RewardTheta is required to be fractional, we perform linear interpolation between CumsumBaseline(⌊theta⌋) and CumsumBaseline(⌈theta⌉). The effectiveNetworkTime argument is ceiling of theta. The result is a fractional effectiveNetworkTime (theta) in Q.128 format.

func InitBaselinePower

func InitBaselinePower() abi.StoragePower

Initialize baseline power for epoch -1 so that baseline power at epoch 0 is BaselineInitialValue.

func SlowConvenientBaselineForEpoch

func SlowConvenientBaselineForEpoch(targetEpoch abi.ChainEpoch) abi.StoragePower

SlowConvenientBaselineForEpoch computes baseline power for use in epoch t by calculating the value of ThisEpochBaselinePower that shows up in block at t - 1 It multiplies ~t times so it should not be used in actor code directly. It is exported as convenience for consuming node.

Types

type Actor

type Actor struct{}

func (Actor) AwardBlockReward

func (a Actor) AwardBlockReward(rt runtime.Runtime, params *AwardBlockRewardParams) *abi.EmptyValue

Awards a reward to a block producer. This method is called only by the system actor, implicitly, as the last message in the evaluation of a block. The system actor thus computes the parameters and attached value.

The reward includes two components: - the epoch block reward, computed and paid from the reward actor's balance, - the block gas reward, expected to be transferred to the reward actor with this invocation.

The reward is reduced before the residual is credited to the block producer, by: - a penalty amount, provided as a parameter, which is burnt,

func (Actor) Code

func (a Actor) Code() cid.Cid

func (Actor) Constructor

func (a Actor) Constructor(rt runtime.Runtime, currRealizedPower *abi.StoragePower) *abi.EmptyValue

func (Actor) Exports

func (a Actor) Exports() []interface{}

func (Actor) IsSingleton

func (a Actor) IsSingleton() bool

func (Actor) State

func (a Actor) State() cbor.Er

func (Actor) ThisEpochReward

func (a Actor) ThisEpochReward(rt runtime.Runtime, _ *abi.EmptyValue) *ThisEpochRewardReturn

The award value used for the current epoch, updated at the end of an epoch through cron tick. In the case previous epochs were null blocks this is the reward value as calculated at the last non-null epoch.

func (Actor) UpdateNetworkKPI

func (a Actor) UpdateNetworkKPI(rt runtime.Runtime, currRealizedPower *abi.StoragePower) *abi.EmptyValue

Called at the end of each epoch by the power actor (in turn by its cron hook). This is only invoked for non-empty tipsets, but catches up any number of null epochs to compute the next epoch reward.

type AwardBlockRewardParams

type AwardBlockRewardParams = reward0.AwardBlockRewardParams

type AwardBlockRewardParams struct {
	Miner     address.Address
	Penalty   abi.TokenAmount // penalty for including bad messages in a block, >= 0
	GasReward abi.TokenAmount // gas reward from all gas fees in a block, >= 0
	WinCount  int64           // number of reward units won, > 0
}

type Spacetime

type Spacetime = big.Int

A quantity of space * time (in byte-epochs) representing power committed to the network for some duration.

type State

type State struct {
	// CumsumBaseline is a target CumsumRealized needs to reach for EffectiveNetworkTime to increase
	// CumsumBaseline and CumsumRealized are expressed in byte-epochs.
	CumsumBaseline Spacetime

	// CumsumRealized is cumulative sum of network power capped by BaselinePower(epoch)
	CumsumRealized Spacetime

	// EffectiveNetworkTime is ceiling of real effective network time `theta` based on
	// CumsumBaselinePower(theta) == CumsumRealizedPower
	// Theta captures the notion of how much the network has progressed in its baseline
	// and in advancing network time.
	EffectiveNetworkTime abi.ChainEpoch

	// EffectiveBaselinePower is the baseline power at the EffectiveNetworkTime epoch
	EffectiveBaselinePower abi.StoragePower

	// The reward to be paid in per WinCount to block producers.
	// The actual reward total paid out depends on the number of winners in any round.
	// This value is recomputed every non-null epoch and used in the next non-null epoch.
	ThisEpochReward abi.TokenAmount
	// Smoothed ThisEpochReward
	ThisEpochRewardSmoothed smoothing.FilterEstimate

	// The baseline power the network is targeting at st.Epoch
	ThisEpochBaselinePower abi.StoragePower

	// Epoch tracks for which epoch the Reward was computed
	Epoch abi.ChainEpoch

	// TotalStoragePowerReward tracks the total FIL awarded to block miners
	TotalStoragePowerReward abi.TokenAmount

	// Simple and Baseline totals are constants used for computing rewards.
	// They are on chain because of a historical fix resetting baseline value
	// in a way that depended on the history leading immediately up to the
	// migration fixing the value.  These values can be moved from state back
	// into a code constant in a subsequent upgrade.
	SimpleTotal   abi.TokenAmount
	BaselineTotal abi.TokenAmount
}

Changed since v0: - ThisEpochRewardSmoothed is not a pointer

func ConstructState

func ConstructState(currRealizedPower abi.StoragePower) *State

func (*State) MarshalCBOR

func (t *State) MarshalCBOR(w io.Writer) error

func (*State) UnmarshalCBOR

func (t *State) UnmarshalCBOR(r io.Reader) error

type StateSummary

type StateSummary struct{}

func CheckStateInvariants

func CheckStateInvariants(st *State, store adt.Store, priorEpoch abi.ChainEpoch, balance abi.TokenAmount) (*StateSummary, *builtin.MessageAccumulator)

type ThisEpochRewardReturn

type ThisEpochRewardReturn = reward6.ThisEpochRewardReturn

Changed since v0: - removed ThisEpochReward (unsmoothed)

type ThisEpochRewardReturn struct {
	ThisEpochRewardSmoothed smoothing.FilterEstimate
	ThisEpochBaselinePower  abi.StoragePower
}