staking docs

Staking
constructor
constructor(address grgVault, address poolRegistry, address rigoToken) public
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
Name
Type
Description
grgVault
address
Address of the Grg vault.
poolRegistry
address
Address of the RigoBlock pool registry.
rigoToken
address
Address of the Grg token.
init
function init() public
Initialize storage owned by this contract.
This function should not be called directly. The StakingProxy contract will call it in attachStakingContract().
MixinConstants
_PPM_DENOMINATOR
uint32 _PPM_DENOMINATOR
_NIL_POOL_ID
bytes32 _NIL_POOL_ID
_NIL_ADDRESS
address _NIL_ADDRESS
_MIN_TOKEN_VALUE
uint256 _MIN_TOKEN_VALUE
MixinDeploymentConstants
constructor
constructor(address grgVault, address poolRegistry, address rigoToken) internal
_implementation
address _implementation
_rigoToken
address _rigoToken
_grgVault
address _grgVault
_poolRegistry
address _poolRegistry
getGrgContract
function getGrgContract() public view virtual returns (contract IRigoToken)
An overridable way to access the deployed GRG contract.
Must be view to allow overrides to access state.
Return Values
Name
Type
Description
[0]
contract IRigoToken
The GRG contract instance.
getGrgVault
function getGrgVault() public view virtual returns (contract IGrgVault)
An overridable way to access the deployed grgVault.
Must be view to allow overrides to access state.
Return Values
Name
Type
Description
[0]
contract IGrgVault
The GRG vault contract.
getPoolRegistry
function getPoolRegistry() public view virtual returns (contract IPoolRegistry)
An overridable way to access the deployed rigoblock pool registry.
Must be view to allow overrides to access state.
Return Values
Name
Type
Description
[0]
contract IPoolRegistry
The pool registry contract.
MixinStorage
stakingContract
address stakingContract
Address of staking contract.
Return Values
_globalStakeByStatus
mapping(uint8 => struct IStructs.StoredBalance) _globalStakeByStatus
_ownerStakeByStatus
mapping(uint8 => mapping(address => struct IStructs.StoredBalance)) _ownerStakeByStatus
_delegatedStakeToPoolByOwner
mapping(address => mapping(bytes32 => struct IStructs.StoredBalance)) _delegatedStakeToPoolByOwner
_delegatedStakeByPoolId
mapping(bytes32 => struct IStructs.StoredBalance) _delegatedStakeByPoolId
poolIdByRbPoolAccount
mapping(address => bytes32) poolIdByRbPoolAccount
Mapping from RigoBlock pool subaccount to pool Id of rigoblock pool
0 RigoBlock pool subaccount address.
Return Values
_poolById
mapping(bytes32 => struct IStructs.Pool) _poolById
rewardsByPoolId
mapping(bytes32 => uint256) rewardsByPoolId
mapping from pool ID to reward balance of members
0 Pool ID.
Return Values
currentEpoch
uint256 currentEpoch
The current epoch.
Return Values
currentEpochStartTimeInSeconds
uint256 currentEpochStartTimeInSeconds
The current epoch start time.
Return Values
_cumulativeRewardsByPool
mapping(bytes32 => mapping(uint256 => struct IStructs.Fraction)) _cumulativeRewardsByPool
_cumulativeRewardsByPoolLastStored
mapping(bytes32 => uint256) _cumulativeRewardsByPoolLastStored
validPops
mapping(address => bool) validPops
Registered RigoBlock Proof_of_Performance contracts, capable of paying protocol fees.
0 The address to check.
Return Values
epochDurationInSeconds
uint256 epochDurationInSeconds
Minimum seconds between epochs.
Return Values
rewardDelegatedStakeWeight
uint32 rewardDelegatedStakeWeight
Return Values
minimumPoolStake
uint256 minimumPoolStake
Minimum amount of stake required in a pool to collect rewards.
Return Values
cobbDouglasAlphaNumerator
uint32 cobbDouglasAlphaNumerator
Numerator for cobb douglas alpha factor.
Return Values
cobbDouglasAlphaDenominator
uint32 cobbDouglasAlphaDenominator
Denominator for cobb douglas alpha factor.
Return Values
poolStatsByEpoch
mapping(bytes32 => mapping(uint256 => struct IStructs.PoolStats)) poolStatsByEpoch
Stats for each pool that generated fees with sufficient stake to earn rewards.
See _minimumPoolStake in MixinParams.
Parameters
Return Values
aggregatedStatsByEpoch
mapping(uint256 => struct IStructs.AggregatedStats) aggregatedStatsByEpoch
Aggregated stats across all pools that generated fees with sufficient stake to earn rewards.
See _minimumPoolStake in MixinParams.
Parameters
Return Values
grgReservedForPoolRewards
uint256 grgReservedForPoolRewards
The GRG balance of this contract that is reserved for pool reward payouts.
Return Values
IGrgVault
StakingProxySet
event StakingProxySet(address stakingProxyAddress)
Emmitted whenever a StakingProxy is set in a vault.
Parameters
Name
Type
Description
stakingProxyAddress
address
Address of the staking proxy contract.
InCatastrophicFailureMode
event InCatastrophicFailureMode(address sender)
Emitted when the Staking contract is put into Catastrophic Failure Mode
Parameters
Name
Type
Description
sender
address
Address of sender (msg.sender)
Deposit
event Deposit(address staker, uint256 amount)
Emitted when Grg Tokens are deposited into the vault.
Parameters
Name
Type
Description
staker
address
Address of the Grg staker.
amount
uint256
of Grg Tokens deposited.
Withdraw
event Withdraw(address staker, uint256 amount)
Emitted when Grg Tokens are withdrawn from the vault.
Parameters
Name
Type
Description
staker
address
Address of the Grg staker.
amount
uint256
of Grg Tokens withdrawn.
GrgProxySet
event GrgProxySet(address grgProxyAddress)
Emitted whenever the Grg AssetProxy is set.
Parameters
Name
Type
Description
grgProxyAddress
address
Address of the Grg transfer proxy.
setStakingProxy
function setStakingProxy(address stakingProxyAddress) external
Sets the address of the StakingProxy contract.
Note that only the contract staker can call this function.
Parameters
Name
Type
Description
stakingProxyAddress
address
Address of Staking proxy contract.
enterCatastrophicFailure
function enterCatastrophicFailure() external
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
function setGrgProxy(address grgProxyAddress) external
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
Name
Type
Description
grgProxyAddress
address
Address of the RigoBlock Grg Proxy.
depositFrom
function depositFrom(address staker, uint256 amount) external
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
Name
Type
Description
staker
address
Address of the Grg staker.
amount
uint256
of Grg Tokens to deposit.
withdrawFrom
function withdrawFrom(address staker, uint256 amount) external
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
Name
Type
Description
staker
address
Address of the Grg staker.
amount
uint256
of Grg Tokens to withdraw.
withdrawAllFrom
function withdrawAllFrom(address staker) external returns (uint256)
Withdraw ALL Grg Tokens to staker from the vault.
Note that this can only be called when in Catastrophic Failure mode.
Parameters
Name
Type
Description
staker
address
Address of the Grg staker.
balanceOf
function balanceOf(address staker) external view returns (uint256)
Returns the balance in Grg Tokens of the staker
Parameters
Name
Type
Description
staker
address
Address of the Grg staker.
Return Values
Name
Type
Description
[0]
uint256
Balance in Grg.
balanceOfGrgVault
function balanceOfGrgVault() external view returns (uint256)
Returns the entire balance of Grg tokens in the vault.
Return Values
Name
Type
Description
[0]
uint256
Balance in Grg.
IStaking
addPopAddress
function addPopAddress(address addr) external
Adds a new proof_of_performance address.
Parameters
Name
Type
Description
addr
address
Address of proof_of_performance contract to add.
createStakingPool
function createStakingPool(address rigoblockPoolAddress) external returns (bytes32 poolId)
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
Name
Type
Description
rigoblockPoolAddress
address
Adds rigoblock pool to the created staking pool for convenience if non-null.
Return Values
Name
Type
Description
poolId
bytes32
The unique pool id generated for this pool.
setStakingPalAddress
function setStakingPalAddress(bytes32 poolId, address newStakingPalAddress) external
Allows the operator to update the staking pal address.
Parameters
Name
Type
Description
poolId
bytes32
Unique id of pool.
newStakingPalAddress
address
Address of the new staking pal.
decreaseStakingPoolOperatorShare
function decreaseStakingPoolOperatorShare(bytes32 poolId, uint32 newOperatorShare) external
Decreases the operator share for the given pool (i.e. increases pool rewards for members).
Parameters
Name
Type
Description
poolId
bytes32
Unique Id of pool.
newOperatorShare
uint32
The newly decreased percentage of any rewards owned by the operator.
endEpoch
function endEpoch() external returns (uint256 numPoolsToFinalize)
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
Name
Type
Description
numPoolsToFinalize
uint256
The number of unfinalized pools.
finalizePool
function finalizePool(bytes32 poolId) external
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
Name
Type
Description
poolId
bytes32
The pool ID to finalize.
init
function init() external
Initialize storage owned by this contract.
This function should not be called directly. The StakingProxy contract will call it in attachStakingContract().
moveStake
function moveStake(struct IStructs.StakeInfo from, struct IStructs.StakeInfo to, uint256 amount) external
Moves stake between statuses: 'undelegated' or 'delegated'.
Delegated stake can also be moved between pools. This change comes into effect next epoch.
Parameters
Name
Type
Description
from
struct IStructs.StakeInfo
Status to move stake out of.
to
struct IStructs.StakeInfo
Status to move stake into.
amount
uint256
Amount of stake to move.
creditPopReward
function creditPopReward(address poolAccount, uint256 popReward) external payable
Credits the value of a pool's pop reward.
Only a known RigoBlock pop can call this method. See (MixinPopManager).
Parameters
Name
Type
Description
poolAccount
address
The address of the rigoblock pool account.
popReward
uint256
The pop reward.
removePopAddress
function removePopAddress(address addr) external
Removes an existing proof_of_performance address.
Parameters
Name
Type
Description
addr
address
Address of proof_of_performance contract to remove.
setParams
function setParams(uint256 _epochDurationInSeconds, uint32 _rewardDelegatedStakeWeight, uint256 _minimumPoolStake, uint32 _cobbDouglasAlphaNumerator, uint32 _cobbDouglasAlphaDenominator) external
Set all configurable parameters at once.
Parameters
Name
Type
Description
_epochDurationInSeconds
uint256
Minimum seconds between epochs.
_rewardDelegatedStakeWeight
uint32
How much delegated stake is weighted vs operator stake, in ppm.
_minimumPoolStake
uint256
Minimum amount of stake required in a pool to collect rewards.
_cobbDouglasAlphaNumerator
uint32
Numerator for cobb douglas alpha factor.
_cobbDouglasAlphaDenominator
uint32
Denominator for cobb douglas alpha factor.
stake
function stake(uint256 amount) external
Stake GRG tokens. Tokens are deposited into the GRG Vault.
Unstake to retrieve the GRG. Stake is in the 'Active' status.
Parameters
Name
Type
Description
amount
uint256
of GRG to stake.
unstake
function unstake(uint256 amount) external
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
Name
Type
Description
amount
uint256
of GRG to unstake.
withdrawDelegatorRewards
function withdrawDelegatorRewards(bytes32 poolId) external
Withdraws the caller's GRG rewards that have accumulated until the last epoch.
Parameters
Name
Type
Description
poolId
bytes32
Unique id of pool.
computeRewardBalanceOfDelegator
function computeRewardBalanceOfDelegator(bytes32 poolId, address member) external view returns (uint256 reward)
Computes the reward balance in GRG of a specific member of a pool.
Parameters
Name
Type
Description
poolId
bytes32
Unique id of pool.
member
address
The member of the pool.
Return Values
Name
Type
Description
reward
uint256
Balance in GRG.
computeRewardBalanceOfOperator
function computeRewardBalanceOfOperator(bytes32 poolId) external view returns (uint256 reward)
Computes the reward balance in GRG of the operator of a pool.
Parameters
Name
Type
Description
poolId
bytes32
Unique id of pool.
Return Values
Name
Type
Description
reward
uint256
Balance in GRG.
getCurrentEpochEarliestEndTimeInSeconds
function getCurrentEpochEarliestEndTimeInSeconds() external view returns (uint256)
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
Name
Type
Description
[0]
uint256
Time in seconds.
getGlobalStakeByStatus
function getGlobalStakeByStatus(enum IStructs.StakeStatus stakeStatus) external view returns (struct IStructs.StoredBalance balance)
Gets global stake for a given status.
Parameters
Name
Type
Description
stakeStatus
enum IStructs.StakeStatus
UNDELEGATED or DELEGATED
Return Values
Name
Type
Description
balance
struct IStructs.StoredBalance
Global stake for given status.
getOwnerStakeByStatus
function getOwnerStakeByStatus(address staker, enum IStructs.StakeStatus stakeStatus) external view returns (struct IStructs.StoredBalance balance)
Gets an owner's stake balances by status.
Parameters
Name
Type
Description
staker
address
Owner of stake.
stakeStatus
enum IStructs.StakeStatus
UNDELEGATED or DELEGATED
Return Values
Name
Type
Description
balance
struct IStructs.StoredBalance
Owner's stake balances for given status.
getTotalStake
function getTotalStake(address staker) external view returns (uint256)
Returns the total stake for a given staker.
Parameters
Name
Type
Description
staker
address
of stake.
Return Values
Name
Type
Description
[0]
uint256
Total GRG staked by staker.
getParams
function getParams() external view returns (uint256 _epochDurationInSeconds, uint32 _rewardDelegatedStakeWeight, uint256 _minimumPoolStake, uint32 _cobbDouglasAlphaNumerator, uint32 _cobbDouglasAlphaDenominator)
Retrieves all configurable parameter values.
Return Values
Name
Type
Description
_epochDurationInSeconds
uint256
Minimum seconds between epochs.
_rewardDelegatedStakeWeight
uint32
How much delegated stake is weighted vs operator stake, in ppm.
_minimumPoolStake
uint256
Minimum amount of stake required in a pool to collect rewards.
_cobbDouglasAlphaNumerator
uint32
Numerator for cobb douglas alpha factor.
_cobbDouglasAlphaDenominator
uint32
Denominator for cobb douglas alpha factor.
getStakeDelegatedToPoolByOwner
function getStakeDelegatedToPoolByOwner(address staker, bytes32 poolId) external view returns (struct IStructs.StoredBalance balance)
Returns stake delegated to pool by staker.
Parameters
Name	Type	Description
grgVault	address	Address of the Grg vault.
poolRegistry	address	Address of the RigoBlock pool registry.
rigoToken	address	Address of the Grg token.
Name	Type	Description
staker	address	Address of the Grg staker.
amount	uint256	of Grg Tokens deposited.
Name	Type	Description
poolId	bytes32	Unique id of pool.
newStakingPalAddress	address	Address of the new staking pal.
Name	Type	Description
from	struct IStructs.StakeInfo	Status to move stake out of.
to	struct IStructs.StakeInfo	Status to move stake into.
amount	uint256	Amount of stake to move.
Name	Type	Description
poolAccount	address	The address of the rigoblock pool account.
popReward	uint256	The pop reward.
Name	Type	Description
_epochDurationInSeconds	uint256	Minimum seconds between epochs.
_rewardDelegatedStakeWeight	uint32	How much delegated stake is weighted vs operator stake, in ppm.
_minimumPoolStake	uint256	Minimum amount of stake required in a pool to collect rewards.
_cobbDouglasAlphaNumerator	uint32	Numerator for cobb douglas alpha factor.
_cobbDouglasAlphaDenominator	uint32	Denominator for cobb douglas alpha factor.
Name	Type	Description
staker	address	Owner of stake.
stakeStatus	enum IStructs.StakeStatus	UNDELEGATED or DELEGATED