staking docs
Staking
constructor
Setting owner to null address prevents admin direct calls to implementation.
Initializing immutable implementation address is used to allow delegatecalls only. Direct calls to the implementation contract are effectively locked.
Parameters
init
Initialize storage owned by this contract.
This function should not be called directly. The StakingProxy contract will call it in attachStakingContract()
.
MixinConstants
_PPM_DENOMINATOR
_NIL_POOL_ID
_NIL_ADDRESS
_MIN_TOKEN_VALUE
MixinDeploymentConstants
constructor
_implementation
_rigoToken
_grgVault
_poolRegistry
getGrgContract
An overridable way to access the deployed GRG contract.
Must be view to allow overrides to access state.
Return Values
getGrgVault
An overridable way to access the deployed grgVault.
Must be view to allow overrides to access state.
Return Values
getPoolRegistry
An overridable way to access the deployed rigoblock pool registry.
Must be view to allow overrides to access state.
Return Values
MixinStorage
stakingContract
Address of staking contract.
Return Values
_globalStakeByStatus
_ownerStakeByStatus
_delegatedStakeToPoolByOwner
_delegatedStakeByPoolId
poolIdByRbPoolAccount
Mapping from RigoBlock pool subaccount to pool Id of rigoblock pool
0 RigoBlock pool subaccount address.
Return Values
_poolById
rewardsByPoolId
mapping from pool ID to reward balance of members
0 Pool ID.
Return Values
currentEpoch
The current epoch.
Return Values
currentEpochStartTimeInSeconds
The current epoch start time.
Return Values
_cumulativeRewardsByPool
_cumulativeRewardsByPoolLastStored
validPops
Registered RigoBlock Proof_of_Performance contracts, capable of paying protocol fees.
0 The address to check.
Return Values
epochDurationInSeconds
Minimum seconds between epochs.
Return Values
rewardDelegatedStakeWeight
Return Values
minimumPoolStake
Minimum amount of stake required in a pool to collect rewards.
Return Values
cobbDouglasAlphaNumerator
Numerator for cobb douglas alpha factor.
Return Values
cobbDouglasAlphaDenominator
Denominator for cobb douglas alpha factor.
Return Values
poolStatsByEpoch
Stats for each pool that generated fees with sufficient stake to earn rewards.
See _minimumPoolStake
in MixinParams
.
Parameters
Return Values
aggregatedStatsByEpoch
Aggregated stats across all pools that generated fees with sufficient stake to earn rewards.
See _minimumPoolStake
in MixinParams.
Parameters
Return Values
grgReservedForPoolRewards
The GRG balance of this contract that is reserved for pool reward payouts.
Return Values
IGrgVault
StakingProxySet
Emmitted whenever a StakingProxy is set in a vault.
Parameters
InCatastrophicFailureMode
Emitted when the Staking contract is put into Catastrophic Failure Mode
Parameters
Deposit
Emitted when Grg Tokens are deposited into the vault.
Parameters
Withdraw
Emitted when Grg Tokens are withdrawn from the vault.
Parameters
GrgProxySet
Emitted whenever the Grg AssetProxy is set.
Parameters
setStakingProxy
Sets the address of the StakingProxy contract.
Note that only the contract staker can call this function.
Parameters
enterCatastrophicFailure
Vault enters into Catastrophic Failure Mode.
*** WARNING - ONCE IN CATOSTROPHIC FAILURE MODE, YOU CAN NEVER GO BACK! *** Note that only the contract staker can call this function.
setGrgProxy
Sets the Grg proxy.
Note that only the contract staker can call this. Note that this can only be called when not in Catastrophic Failure mode.
Parameters
depositFrom
Deposit an amount
of Grg Tokens from staker
into the vault.
Note that only the Staking contract can call this. Note that this can only be called when not in Catastrophic Failure mode.
Parameters
withdrawFrom
Withdraw an amount
of Grg Tokens to staker
from the vault.
Note that only the Staking contract can call this. Note that this can only be called when not in Catastrophic Failure mode.
Parameters
withdrawAllFrom
Withdraw ALL Grg Tokens to staker
from the vault.
Note that this can only be called when in Catastrophic Failure mode.
Parameters
balanceOf
Returns the balance in Grg Tokens of the staker
Parameters
Return Values
balanceOfGrgVault
Returns the entire balance of Grg tokens in the vault.
Return Values
IStaking
addPopAddress
Adds a new proof_of_performance address.
Parameters
createStakingPool
Create a new staking pool. The sender will be the staking pal of this pool.
Note that a staking pal must be payable. When governance updates registry address, pools must be migrated to new registry, or this contract must query from both.
Parameters
Return Values
setStakingPalAddress
Allows the operator to update the staking pal address.
Parameters
decreaseStakingPoolOperatorShare
Decreases the operator share for the given pool (i.e. increases pool rewards for members).
Parameters
endEpoch
Begins a new epoch, preparing the prior one for finalization.
Throws if not enough time has passed between epochs or if the previous epoch was not fully finalized.
Return Values
finalizePool
Instantly finalizes a single pool that earned rewards in the previous epoch,
crediting it rewards for members and withdrawing operator's rewards as GRG. This can be called by internal functions that need to finalize a pool immediately. Does nothing if the pool is already finalized or did not earn rewards in the previous epoch.
Parameters
init
Initialize storage owned by this contract.
This function should not be called directly. The StakingProxy contract will call it in attachStakingContract()
.
moveStake
Moves stake between statuses: 'undelegated' or 'delegated'.
Delegated stake can also be moved between pools. This change comes into effect next epoch.
Parameters
creditPopReward
Credits the value of a pool's pop reward.
Only a known RigoBlock pop can call this method. See (MixinPopManager).
Parameters
removePopAddress
Removes an existing proof_of_performance address.
Parameters
setParams
Set all configurable parameters at once.
Parameters
stake
Stake GRG tokens. Tokens are deposited into the GRG Vault.
Unstake to retrieve the GRG. Stake is in the 'Active' status.
Parameters
unstake
Unstake. Tokens are withdrawn from the GRG Vault and returned to the staker.
Stake must be in the 'undelegated' status in both the current and next epoch in order to be unstaked.
Parameters
withdrawDelegatorRewards
Withdraws the caller's GRG rewards that have accumulated until the last epoch.
Parameters
computeRewardBalanceOfDelegator
Computes the reward balance in GRG of a specific member of a pool.
Parameters
Return Values
computeRewardBalanceOfOperator
Computes the reward balance in GRG of the operator of a pool.
Parameters
Return Values
getCurrentEpochEarliestEndTimeInSeconds
Returns the earliest end time in seconds of this epoch.
The next epoch can begin once this time is reached. Epoch period = [startTimeInSeconds..endTimeInSeconds)
Return Values
getGlobalStakeByStatus
Gets global stake for a given status.
Parameters
Return Values
getOwnerStakeByStatus
Gets an owner's stake balances by status.
Parameters
Return Values
getTotalStake
Returns the total stake for a given staker.
Parameters
Return Values
getParams
Retrieves all configurable parameter values.
Return Values
getStakeDelegatedToPoolByOwner
Returns stake delegated to pool by staker.
Parameters
Return Values
getStakingPool
Returns a staking pool
Parameters
getStakingPoolStatsThisEpoch
Get stats on a staking pool in this epoch.
Parameters
Return Values
getTotalStakeDelegatedToPool
Returns the total stake delegated to a specific staking pool, across all members.
Parameters
Return Values
getGrgContract
An overridable way to access the deployed GRG contract.
Must be view to allow overrides to access state.
Return Values
getGrgVault
An overridable way to access the deployed grgVault.
Must be view to allow overrides to access state.
Return Values
getPoolRegistry
An overridable way to access the deployed rigoblock pool registry.
Must be view to allow overrides to access state.
Return Values
IStakingEvents
Stake
Emitted by MixinStake when GRG is staked.
Parameters
Unstake
Emitted by MixinStake when GRG is unstaked.
Parameters
MoveStake
Emitted by MixinStake when GRG is unstaked.
Parameters
PopAdded
Emitted by MixinExchangeManager when an exchange is added.
Parameters
PopRemoved
Emitted by MixinExchangeManager when an exchange is removed.
Parameters
StakingPoolEarnedRewardsInEpoch
Emitted by MixinExchangeFees when a pool starts earning rewards in an epoch.
Parameters
EpochEnded
Emitted by MixinFinalizer when an epoch has ended.
Parameters
EpochFinalized
Emitted by MixinFinalizer when an epoch is fully finalized.
Parameters
RewardsPaid
Emitted by MixinFinalizer when rewards are paid out to a pool.
Parameters
ParamsSet
Emitted whenever staking parameters are changed via the setParams()
function.
Parameters
StakingPoolCreated
Emitted by MixinStakingPool when a new pool is created.
Parameters
RbPoolStakingPoolSet
Emitted by MixinStakingPool when a rigoblock pool is added to its staking pool.
Parameters
OperatorShareDecreased
Emitted when a staking pool's operator share is decreased.
Parameters
GrgMintEvent
Emitted when an inflation mint call is executed successfully.
Parameters
CatchStringEvent
Emitted whenever an inflation mint call is reverted.
Parameters
ReturnDataEvent
Emitted to catch any other inflation mint call fail.
Parameters
IStakingProxy
StakingContractAttachedToProxy
Emitted by StakingProxy when a staking contract is attached.
Parameters
StakingContractDetachedFromProxy
Emitted by StakingProxy when a staking contract is detached.
attachStakingContract
Attach a staking contract; future calls will be delegated to the staking contract.
Note that this is callable only by an authorized address.
Parameters
detachStakingContract
Detach the current staking contract.
Note that this is callable only by an authorized address.
batchExecute
Batch executes a series of calls to the staking contract.
Parameters
assertValidStorageParams
Asserts initialziation parameters are correct.
Asserts that an epoch is between 5 and 30 days long. Asserts that 0 < cobb douglas alpha value <= 1. Asserts that a stake weight is <= 100%. Asserts that pools allow >= 1 maker. Asserts that all addresses are initialized.
IStorage
stakingContract
Address of staking contract.
Return Values
poolIdByRbPoolAccount
Mapping from RigoBlock pool subaccount to pool Id of rigoblock pool
0 RigoBlock pool subaccount address.
Return Values
rewardsByPoolId
mapping from pool ID to reward balance of members
0 Pool ID.
Return Values
currentEpoch
The current epoch.
Return Values
currentEpochStartTimeInSeconds
The current epoch start time.
Return Values
validPops
Registered RigoBlock Proof_of_Performance contracts, capable of paying protocol fees.
0 The address to check.
Return Values
epochDurationInSeconds
Minimum seconds between epochs.
Return Values
rewardDelegatedStakeWeight
Return Values
minimumPoolStake
Minimum amount of stake required in a pool to collect rewards.
Return Values
cobbDouglasAlphaNumerator
Numerator for cobb douglas alpha factor.
Return Values
cobbDouglasAlphaDenominator
Denominator for cobb douglas alpha factor.
Return Values
poolStatsByEpoch
Stats for each pool that generated fees with sufficient stake to earn rewards.
See _minimumPoolStake
in MixinParams
.
Parameters
Return Values
aggregatedStatsByEpoch
Aggregated stats across all pools that generated fees with sufficient stake to earn rewards.
See _minimumPoolStake
in MixinParams.
Parameters
Return Values
grgReservedForPoolRewards
The GRG balance of this contract that is reserved for pool reward payouts.
Return Values
IStorageInit
init
Initialize storage owned by this contract.
IStructs
PoolStats
AggregatedStats
StoredBalance
StakeStatus
StakeInfo
Fraction
Pool
LibCobbDouglas
cobbDouglas
The cobb-douglas function used to compute fee-based rewards for staking pools in a given epoch. This function does not perform bounds checking on the inputs, but the following conditions need to be true: 0 <= fees / totalFees <= 1 0 <= stake / totalStake <= 1 0 <= alphaNumerator / alphaDenominator <= 1
Parameters
Return Values
LibFixedMath
Signed, fixed-point, 127-bit precision math library.
FIXED_1
MIN_FIXED_VAL
FIXED_1_SQUARED
LN_MAX_VAL
LN_MIN_VAL
EXP_MAX_VAL
EXP_MIN_VAL
mul
Returns the multiplication of two fixed point numbers, reverting on overflow.
div
Returns the division of two fixed point numbers.
mulDiv
Performs (a * n) / d, without scaling for precision.
uintMul
Returns the unsigned integer result of multiplying a fixed-point number with an integer, reverting if the multiplication overflows. Negative results are clamped to zero.
toFixed
Convert unsigned n
/ d
to a fixed-point number. Reverts if n
/ d
is too large to fit in a fixed-point number.
ln
Get the natural logarithm of a fixed-point number 0 < x
<= LN_MAX_VAL
exp
Compute the natural exponent for a fixed-point number EXP_MIN_VAL <= x
<= 1
_mul
Returns the multiplication two numbers, reverting on overflow.
_div
Returns the division of two numbers, reverting on division by zero.
LibSafeDowncast
downcastToUint96
Safely downcasts to a uint96 Note that this reverts if the input value is too large.
downcastToUint64
Safely downcasts to a uint64 Note that this reverts if the input value is too large.
MixinPopManager
addPopAddress
Adds a new proof_of_performance address.
Parameters
removePopAddress
Removes an existing proof_of_performance address.
Parameters
MixinPopRewards
onlyPop
Asserts that the call is coming from a valid pop.
creditPopReward
Credits the value of a pool's pop reward.
Only a known RigoBlock pop can call this method. See (MixinPopManager).
Parameters
getStakingPoolStatsThisEpoch
Get stats on a staking pool in this epoch.
Parameters
Return Values
_computeMembersAndWeightedStake
Computes the members and weighted stake for a pool at the current epoch.
Parameters
Return Values
MixinStake
stake
Stake GRG tokens. Tokens are deposited into the GRG Vault.
Unstake to retrieve the GRG. Stake is in the 'Active' status.
Parameters
unstake
Unstake. Tokens are withdrawn from the GRG Vault and returned to the staker.
Stake must be in the 'undelegated' status in both the current and next epoch in order to be unstaked.
Parameters
moveStake
Moves stake between statuses: 'undelegated' or 'delegated'.
Delegated stake can also be moved between pools. This change comes into effect next epoch.
Parameters
_delegateStake
Delegates a owners stake to a staking pool.
Parameters
_undelegateStake
Un-Delegates a owners stake from a staking pool.
Parameters
MixinStakeBalances
getGlobalStakeByStatus
Gets global stake for a given status.
Parameters
Return Values
getOwnerStakeByStatus
Gets an owner's stake balances by status.
Parameters
Return Values
getTotalStake
Returns the total stake for a given staker.
Parameters
Return Values
getStakeDelegatedToPoolByOwner
Returns stake delegated to pool by staker.
Parameters
Return Values
getTotalStakeDelegatedToPool
Returns the total stake delegated to a specific staking pool, across all members.
Parameters
Return Values
MixinStakeStorage
This mixin contains logic for managing stake storage.
_moveStake
Moves stake between states: 'undelegated' or 'delegated'. This change comes into effect next epoch.
Parameters
_loadCurrentBalance
Loads a balance from storage and updates its fields to reflect values for the current epoch.
Parameters
Return Values
_increaseCurrentAndNextBalance
Increments both the current
and next
fields.
Parameters
_decreaseCurrentAndNextBalance
Decrements both the current
and next
fields.
Parameters
_increaseNextBalance
Increments the next
field (but not the current
field).
Parameters
_decreaseNextBalance
Decrements the next
field (but not the current
field).
Parameters
_storeBalance
Stores a balance in storage.
Parameters
_arePointersEqual
Returns true iff storage pointers resolve to same storage location.
Parameters
Return Values
MixinCumulativeRewards
_isCumulativeRewardSet
returns true iff Cumulative Rewards are set
_addCumulativeReward
Sets a pool's cumulative delegator rewards for the current epoch, given the rewards earned and stake from the last epoch, which will be summed with the previous cumulative rewards for this pool. If the last cumulative reward epoch is the current epoch, this is a no-op.
Parameters
_updateCumulativeReward
Sets a pool's cumulative delegator rewards for the current epoch, using the last stored cumulative rewards. If we've already set a CR for this epoch, this is a no-op.
Parameters
_computeMemberRewardOverInterval
Computes a member's reward over a given epoch interval.
Parameters
Return Values
_getCumulativeRewardAtEpoch
Fetch the cumulative reward for a given epoch. If the corresponding CR does not exist in state, then we backtrack to find its value by querying epoch-1
and then most recent CR.
Parameters
Return Values
MixinStakingPool
onlyStakingPoolOperator
Asserts that the sender is the operator of the input pool.