reward

Documentation

Index

• Constants
• Variables
• func BaselinePowerFromPrev(prevEpochBaselinePower abi.StoragePower) abi.StoragePower
• func ComputeRTheta(effectiveNetworkTime abi.ChainEpoch, ...) big.Int
• func InitBaselinePower() abi.StoragePower
• type AwardBlockRewardParams
  • func (t *AwardBlockRewardParams) MarshalCBOR(w io.Writer) error
  • func (t *AwardBlockRewardParams) UnmarshalCBOR(r io.Reader) error
• 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, _ adt.Store, priorEpoch abi.ChainEpoch, balance abi.TokenAmount) (*StateSummary, *builtin.MessageAccumulator)
• type ThisEpochRewardReturn
  • func (t *ThisEpochRewardReturn) MarshalCBOR(w io.Writer) error
  • func (t *ThisEpochRewardReturn) UnmarshalCBOR(r io.Reader) error

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

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 Methods = map[abi.MethodNum]builtin.MethodMeta{
	1: {"Constructor", *new(func(*abi.StoragePower) *abi.EmptyValue)},
	2: {"AwardBlockReward", *new(func(*AwardBlockRewardParams) *abi.EmptyValue)},
	3: {"ThisEpochReward", *new(func(*abi.EmptyValue) *ThisEpochRewardReturn)},
	4: {"UpdateNetworkKPI", *new(func(*abi.StoragePower) *abi.EmptyValue)},
}

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.

Types

type 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
}

func (*AwardBlockRewardParams) MarshalCBOR

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

func (*AwardBlockRewardParams) UnmarshalCBOR

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

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, _ adt.Store, priorEpoch abi.ChainEpoch, balance abi.TokenAmount) (*StateSummary, *builtin.MessageAccumulator)

type ThisEpochRewardReturn

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

func (*ThisEpochRewardReturn) MarshalCBOR

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

func (*ThisEpochRewardReturn) UnmarshalCBOR

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