RandomBeacon
RandomBeacon
This file documents a contract which is not yet deployed to Mainnet.
Keep Random Beacon contract. It lets to request a new relay entry and validates the new relay entry provided by the network. This contract is in charge of all other Random Beacon activities such as group lifecycle or slashing.
Should be owned by the governance contract controlling Random Beacon parameters.
genesisSeed
Seed value used for the genesis group selection. https://www.wolframalpha.com/input/?i=pi+to+78+digits
_callbackGasLimit
Relay entry callback gas limit. This is the gas limit with which callback function provided in the relay request transaction is executed. The callback is executed with a new relay entry value in the same transaction the relay entry is submitted.
_groupCreationFrequency
The frequency of new group creation. Groups are created with a fixed frequency of relay requests.
_maliciousDkgResultSlashingAmount
Slashing amount for submitting a malicious DKG result. Every DKG result submitted can be challenged for the time of dkg.ResultChallengePeriodLength
. If the DKG result submitted is challenged and proven to be malicious, the operator who submitted the malicious result is slashed for _maliciousDkgResultSlashingAmount
.
_unauthorizedSigningSlashingAmount
Slashing amount when an unauthorized signing has been proved, which means the private key leaked and all the group members should be punished.
_sortitionPoolRewardsBanDuration
Duration of the sortition pool rewards ban imposed on operators who misbehaved during DKG by being inactive or disqualified and for operators that were identified by the rest of group members as inactive via notifyOperatorInactivity
.
_relayEntryTimeoutNotificationRewardMultiplier
Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about relay entry timeout. Notifiers are rewarded from a notifiers treasury pool. For example, if notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected.
_unauthorizedSigningNotificationRewardMultiplier
Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about unauthorized signing. Notifiers are rewarded from a notifiers treasury pool. For example, if a notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected.
_dkgMaliciousResultNotificationRewardMultiplier
Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about a malicious DKG result. Notifiers are rewarded from a notifiers treasury pool. For example, if notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected.
_dkgResultSubmissionGas
Calculated gas cost for submitting a DKG result. This will be refunded as part of the DKG approval process. It is in the submitter's interest to not skip his priority turn on the approval, otherwise the refund of the DKG submission will be refunded to another group member that will call the DKG approve function.
_dkgResultApprovalGasOffset
Gas that is meant to balance the DKG result approval's overall cost. Can be updated by the governance based on the current market conditions.
_notifyOperatorInactivityGasOffset
Gas that is meant to balance the operator inactivity notification cost. Can be updated by the governance based on the current market conditions.
_relayEntrySubmissionGasOffset
Gas that is meant to balance the relay entry submission cost. Can be updated by the governance based on the current market conditions.
inactivityClaimNonce
Stores current operator inactivity claim nonce for given group. Each claim is made with an unique nonce which protects against claim replay.
authorizedRequesters
Authorized addresses that can request a relay entry.
sortitionPool
tToken
staking
authorization
dkg
groups
relay
callback
AuthorizationParametersUpdated
RelayEntryParametersUpdated
GroupCreationParametersUpdated
RewardParametersUpdated
SlashingParametersUpdated
GasParametersUpdated
RequesterAuthorizationUpdated
DkgStarted
DkgResultSubmitted
DkgTimedOut
DkgResultApproved
DkgResultChallenged
DkgMaliciousResultSlashed
DkgMaliciousResultSlashingFailed
DkgStateLocked
DkgSeedTimedOut
GroupRegistered
RelayEntryRequested
RelayEntrySubmitted
RelayEntryTimedOut
RelayEntryDelaySlashed
RelayEntryDelaySlashingFailed
RelayEntryTimeoutSlashed
RelayEntryTimeoutSlashingFailed
UnauthorizedSigningSlashed
UnauthorizedSigningSlashingFailed
CallbackFailed
InactivityClaimed
OperatorRegistered
AuthorizationIncreased
AuthorizationDecreaseRequested
AuthorizationDecreaseApproved
InvoluntaryAuthorizationDecreaseFailed
OperatorJoinedSortitionPool
OperatorStatusUpdated
constructor
Assigns initial values to parameters to make the beacon work safely. These parameters are just proposed defaults and they might be updated with update*
functions after the contract deployment and before transferring the ownership to the governance contract.
onlyStakingContract
onlyReimbursableAdmin
updateAuthorizationParameters
Updates the values of authorization parameters.
Can be called only by the contract guvnor, which should be the random beacon governance contract. The caller is responsible for validating parameters.
Parameters
updateRelayEntryParameters
Updates the values of relay entry parameters.
Can be called only by the contract guvnor, which should be the random beacon governance contract. The caller is responsible for validating parameters.
Parameters
updateGroupCreationParameters
Updates the values of group creation parameters.
Can be called only by the contract guvnor, which should be the random beacon governance contract. The caller is responsible for validating parameters.
Parameters
updateRewardParameters
Updates the values of reward parameters.
Can be called only by the contract guvnor, which should be the random beacon governance contract. The caller is responsible for validating parameters.
Parameters
updateSlashingParameters
Updates the values of slashing parameters.
Can be called only by the contract guvnor, which should be the random beacon governance contract. The caller is responsible for validating parameters.
Parameters
updateGasParameters
Updates the values of gas parameters.
Can be called only by the contract guvnor, which should be the random beacon governance contract. The caller is responsible for validating parameters.
Parameters
setRequesterAuthorization
Set authorization for requesters that can request a relay entry.
Can be called only by the contract guvnor, which should be the random beacon governance contract.
Parameters
withdrawRewards
Withdraws application rewards for the given staking provider. Rewards are withdrawn to the staking provider's beneficiary address set in the staking contract. Reverts if staking provider has not registered the operator address.
Emits RewardsWithdrawn
event.
withdrawIneligibleRewards
Withdraws rewards belonging to operators marked as ineligible for sortition pool rewards.
Can be called only by the contract guvnor, which should be the random beacon governance contract.
Parameters
registerOperator
Used by staking provider to set operator address that will operate a node. The given staking provider can set operator address only one time. The operator address can not be changed and must be unique. Reverts if the operator is already set for the staking provider or if the operator address is already in use. Reverts if there is a pending authorization decrease for the staking provider.
joinSortitionPool
Lets the operator join the sortition pool. The operator address must be known - before calling this function, it has to be appointed by the staking provider by calling registerOperator
. Also, the operator must have the minimum authorization required by the beacon. Function reverts if there is no minimum stake authorized or if the operator is not known. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay.
updateOperatorStatus
Updates status of the operator in the sortition pool. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. Function reverts if the operator is not known.
authorizationIncreased
Used by T staking contract to inform the beacon that the authorized stake amount for the given staking provider increased.
Reverts if the authorization amount is below the minimum.
The function is not updating the sortition pool. Sortition pool state needs to be updated by the operator with a call to joinSortitionPool
or updateOperatorStatus
.
Can only be called by T staking contract.
authorizationDecreaseRequested
Used by T staking contract to inform the beacon that the authorization decrease for the given staking provider has been requested.
Reverts if the amount after deauthorization would be non-zero and lower than the minimum authorization.
Reverts if another authorization decrease request is pending for the staking provider and not enough time passed since the original request (see authorizationDecreaseChangePeriod
).
If the operator is not known (registerOperator
was not called) it lets to approveAuthorizationDecrease
immediately. If the operator is known (registerOperator
was called), the operator needs to update state of the sortition pool with a call to joinSortitionPool
or updateOperatorStatus
. After the sortition pool state is in sync, authorization decrease delay starts.
After authorization decrease delay passes, authorization decrease request needs to be approved with a call to approveAuthorizationDecrease
function.
If there is a pending authorization decrease request, it is overwritten, but only if enough time passed since the original request. Otherwise, the function reverts.
Can only be called by T staking contract.
approveAuthorizationDecrease
Approves the previously registered authorization decrease request. Reverts if authorization decrease delay has not passed yet or if the authorization decrease was not requested for the given staking provider.
involuntaryAuthorizationDecrease
Used by T staking contract to inform the beacon the authorization has been decreased for the given staking provider involuntarily, as a result of slashing.
If the operator is not known (registerOperator
was not called) the function does nothing. The operator was never in a sortition pool so there is nothing to update.
If the operator is known, sortition pool is unlocked, and the operator is in the sortition pool, the sortition pool state is updated. If the sortition pool is locked, update needs to be postponed. Every other staker is incentivized to call updateOperatorStatus
for the problematic operator to increase their own rewards in the pool.
genesis
Triggers group selection if there are no active groups.
submitDkgResult
\x19Ethereum signed message:
before signing, so the message to sign is: \x19Ethereum signed message:\n${keccak256(chainID,groupPubKey,misbehaved,startBlock)}
Parameters
notifyDkgTimeout
Notifies about DKG timeout.
approveDkgResult
Approves DKG result. Can be called when the challenge period for the submitted result is finished. Considers the submitted result as valid, bans misbehaved group members from the sortition pool rewards, and completes the group creation by activating the candidate group. For the first submitterPrecedencePeriodLength
blocks after the end of the challenge period can be called only by the DKG result submitter. After that time, can be called by anyone.
Parameters
challengeDkgResult
Challenges DKG result. If the submitted result is proved to be invalid it reverts the DKG back to the result submission phase. It removes a candidate group that was previously registered with the DKG result submission.
Due to EIP-150 1/64 of the gas is not forwarded to the call, and will be kept to execute the remaining operations in the function after the call inside the try-catch. To eliminate a class of attacks related to the gas limit manipulation, this function requires an extra amount of gas to be left at the end of the execution.
Parameters
getGroupCreationState
Check current group creation state.
hasDkgTimedOut
Checks if DKG timed out. The DKG timeout period includes time required for off-chain protocol execution and time for the result publication for all group members. After this time result cannot be submitted and DKG can be notified about the timeout.
Return Values
getGroupsRegistry
getGroup
getGroup
requestRelayEntry
Creates a request to generate a new relay entry, which will include a random number (by signing the previous entry's random number). Requester must be previously authorized by the governance.
Parameters
submitRelayEntry
Creates a new relay entry. Gas-optimized version that can be called only before the soft timeout. This should be the majority of cases.
Parameters
submitRelayEntry
Creates a new relay entry.
Parameters
reportRelayEntryTimeout
Reports a relay entry timeout.
Parameters
reportUnauthorizedSigning
Reports unauthorized groups signing. Must provide a valid signature of the sender's address as a message. Successful signature verification means the private key has been leaked and all group members should be punished by slashing their tokens. Group has to be active or expired. Unauthorized signing cannot be reported for a terminated group. In case of reporting unauthorized signing for a terminated group, or when the signature is invalid, function reverts.
Parameters
notifyOperatorInactivity
Notifies about operators who are inactive. Using this function, a majority of the group can decide about punishing specific group members who constantly fail doing their job. If the provided claim is proved to be valid and signed by sufficient number of group members, operators of members deemed as inactive are banned for sortition pool rewards for duration specified by _sortitionPoolRewardsBanDuration
parameter. The sender of the claim must be one of the claim signers. This function can be called only for active and non-terminated groups.
Parameters
minimumAuthorization
The minimum authorization amount required so that operator can participate in the random beacon. This amount is required to execute slashing for providing a malicious DKG result or when a relay entry times out.
isRelayRequestInProgress
Return Values
eligibleStake
Returns the current value of the staking provider's eligible stake. Eligible stake is defined as the currently authorized stake minus the pending authorization decrease. Eligible stake is what is used for operator's weight in the sortition pool. If the authorized stake minus the pending authorization decrease is below the minimum authorization, eligible stake is 0.
availableRewards
Returns the amount of rewards available for withdrawal for the given staking provider. Reverts if staking provider has not registered the operator address.
pendingAuthorizationDecrease
Returns the amount of stake that is pending authorization decrease for the given staking provider. If no authorization decrease has been requested, returns zero.
remainingAuthorizationDecreaseDelay
Returns the remaining time in seconds that needs to pass before the requested authorization decrease can be approved. If the sortition pool state was not updated yet by the operator after requesting the authorization decrease, returns type(uint64).max
.
stakingProviderToOperator
Returns operator registered for the given staking provider.
operatorToStakingProvider
Returns staking provider of the given operator.
isOperatorUpToDate
Checks if the operator's authorized stake is in sync with operator's weight in the sortition pool. If the operator is not in the sortition pool and their authorized stake is non-zero, function returns false.
isOperatorInPool
Returns true if the given operator is in the sortition pool. Otherwise, returns false.
selectGroup
Selects a new group of operators. Can only be called when DKG is in progress and the pool is locked. At least one operator has to be registered in the pool, otherwise the function fails reverting the transaction.
Return Values
authorizationParameters
Returns authorization-related parameters of the beacon.
The minimum authorization is also returned by minimumAuthorization()
function, as a requirement of IApplication
interface.
Return Values
relayEntryParameters
Returns relay-entry-related parameters of the beacon.
Return Values
groupCreationParameters
Returns group-creation-related parameters of the beacon.
Return Values
rewardParameters
Returns reward-related parameters of the beacon.
Return Values
slashingParameters
Returns slashing-related parameters of the beacon.
Return Values
gasParameters
Returns gas-related parameters of the beacon.
Return Values
Last updated