For the Matic network's Proof of Security based consensus, all the ⅔+1 proof verification and handling of staking, rewards are executed on the Ethereum smart contract.
The whole design follows this philosophy of doing less on the Mainnet contract. It does information verification and pushes all the computation-heavy operations to L2 (Read Heimdall for this doc).
Staking actors (Stakers) are divided into validators, delegators and watchers(for fraud reporting).
StakeManager is the main contract for handling validator related activities like
checkPoint signature verification, reward distribution, slashing and stake management.
Note that from one Ethereum address, a Staker can only be a validator or delegator (It's just a design choice, no hard reasons).
Since the contract is using NFT ID as a source of ownership, change of ownership and signer won't affect anything in the system.
validatorThreshold: Shows the maximum number of validators accepted by the system, also called slots.
- For various accounting done on heimdall for validators and delegator account root is submitted while submitting the
- accRoot is used while
- Allows anyone with amount(Matic tokens) greater
currentValidatorSetSizeis less then
- MUST transfer
amount+heimdallFee, puts validator into auction period for an auctionInterval.(more on auction in auction section)
updateTimeLineupdates special timeline data structure, which keeps track of active validators and active stake for given epoch/checkpoint count.
- One unique
NFTis minted on each new stake/stakeFor call, which can be transferred to anyone but can be owned 1:1 ethereum address.
acceptDelegationset true if validators want to accept delegation,
ValidatorSharecontract is deployed for the validator.
- Remove validator from validator set in next epoch(only valid for current checkpoint once called
- Remove validator's stake from timeline data structure, update count for validator's exit epoch.
- If validator had delegation on collect all rewards and lock delegation contract for new delegations.
unstakingvalidators are put into withdrawal period so that they can be slashed if any fraud found after
unstakingfor pas frauds.
WITHDRAWAL_DELAYperiod is served validator's can call this function and do settlement with stakeManager(get rewards if any, get staked tokens back, burn NFT etc)
- Allows validators to increase their stake by putting new amount or rewards or both.
- MUST update timeline(amount) for active stake.
- Allows validators to withdraw accumulated rewards, must consider getting rewards from delegation contract if validator accepts delegation.
- Allows validators to update signer address(which is used to validate blocks on matic chain and checkpoint sigs on stakeManager)
- Once slashing is implemented there will be cap on how many times a validator can change signer key.
- Validators can top-up their balance for heimdall fee.
- Used to withdraw fee from heimdall.
accountStateRootis updated on each checkpoint, so that validators can provide proof of inclusion in this root for account on heimdall and withdraw fee.
- Note that
accountStateRootis re-written to prevent exits on multiple checkpoints(for old root and save accounting on stakeManager)
accumSlashedAmountis unused atm, will be used for slashing on heimdall if needed.
- Standard erc721 with few restrictions like one token per user and minted in sequential manner.
In order to replace poor performing validator there is periodic auction for each validator slot.
For individual validators there is auction window where wanna be validators can bid their amount and start an auction using
auctionIntervalis over last bidder needs to close the auction in order to confirm and become validator. For which she needs to call
confirmAuctionBidwhich accepts and behave similar to new
stakefunction for upcoming validator and
unStakefor old validator.
Current validator can bid for herself and try to keep that place.
Whole mech dynamically balances the stake value and overall security according to market conditions and use of matic chain.
startAuctionfunction startAuction(uint256 validatorId, /** auction for validator */uint256 amount /** amount greater then old validator's stake */) external;
In order to start a bid or bid higher on already running auction this function is used.
Auction period runs in cycles like
(auctionPeriod--dynasty)--(auctionPeriod--dynasty)--(auctionPeriod--dynasty)so it MUST check for correct auction period.
perceivedStakeFactoris used to calculate exact factor*old stake (note currently it is by default 1 WIP for picking the function).
MUST check for auction from last auction period if any still going on (one can choose to not call
confirmAuctionin order to get her capital out in next auction).
Normally continuous english auction is going on in a
confirmAuctionBidfunction confirmAuctionBid(uint256 validatorId,uint256 heimdallFee, /** for new validator */bool acceptDelegation,bytes calldata signerPubkey) external
MUST check that this is not an auctionPeriod.
If last bidder is owner of
validatorIdbehaviour should be similar to restake.
In second case unStake
validatorIdand add new user as validator from next checkpoint, for the new user behaviour should be similar to stake/stakeFor.
- Writes are meant only for RootChain contract when submitting checkpoints
voteHashon which all validators sign (BFT ⅔+1 agreement)
- This function validates only unique sigs and checks for ⅔+1 power has signed on checkpoint root (inclusion in
voteHashverification in RootChain contract for all data)
currentValidatorSetTotalStakeprovides current active stake.
- Rewards are distributed proportional to validator's stake, more on rewards in below doc.
- Checks if given validator is active validator for current epoch.
Timeline data structure
Diagram trying to explain timeline data structure
Centralised logging contract for both validator and delegation events, Includes few read only functions.
Factory contract to deploy
ValidatorShare contract for each validator who opt-in for delegation.
slash function aren't used currently (part of slashing implementation).