Skip to main content

StMATIC

StMATIC is the core contract which acts as a liquid staking pool. The contract is responsible for deposits, withdrawals, minting and burning liquid tokens, delegating funds to node operators, applying fees and distributing rewards.

StMATIC contract also defines stMATIC, an ERC20 token that represents the account's share of the total supply of MATIC tokens inside Lido on Polygon system. It is a non-rebasable token, which means that the amount of tokens in the user's wallet is not going to change. During time, the value of this token is changing, since the amount of MATIC tokens inside the protocol is not constant. StMATIC will be integrated in variety of DeFi applications across Ethereum and Polygon.

View Methods​

name()​

Returns the name of the token

function name() returns (string)

symbol()​

Returns the symbol of the token, usually a shorter version of the name

function symbol() returns (string)

decimals()​

Returns the number of decimals for getting user representation of a token amount.

function decimals() returns (uint8)

totalSupply()​

Returns the amount of tokens in existence.

function totalSupply() returns (uint256)

balanceOf()​

Returns the amount of tokens owned by the _account

function balanceOf(address _account) returns (uint256)

getTotalStake()​

Returns the total amount of stake the StMatic contract has in a validator

function getTotalStake(IValidatorShare _validatorShare)
        public
        view
        override
        returns (uint256, uint256)

Parameters:​

NameTypeDescription
_validatorShareValidatorShareAn instance of the validator share contract

Returns:​

NameTypeDescription
totalStakeuint256The total staked in the validator

getLiquidRewards()​

Returns the reward accumulated by the StMATIC contract in a specific validator share.

function getLiquidRewards(IValidatorShare _validatorShare)
        external
        view
        override
        returns (uint256)

Parameters:​

NameTypeDescription
_validatorShareValidatorShareAn instance of the validator share contract

Returns:​

NameTypeDescription
rewardsuint256The total rewards accumulated inside the validatorShare contract

getTotalStakeAcrossAllValidators()​

Returns the total delegated MATICs across all validators.

function getTotalStakeAcrossAllValidators()
        public
        view
        override
        returns (uint256)

Returns:​

NameTypeDescription
totaluint256The total delegated MATICs across all validators

getTotalPooledMatic()​

Returns total pooled matic

function getTotalPooledMatic() public view override returns (uint256)

Returns:​

NameTypeDescription
totaluint256The total pooled matic inside the protocol

convertStMaticToMatic()​

Returns the MATIC value of any StMatic amount passed to the function

function convertStMaticToMatic(uint256 _amountInStMatic)
        public
        view
        override
        returns (
            uint256 amountInMatic,
            uint256 totalStMaticAmount,
            uint256 totalPooledMatic
        )

Parameters:​

NameTypeDescription
_amountInStMaticuint256Amount of StMatic to be convert to MATIC

Returns:​

NameTypeDescription
amountInMaticuint256Amount of Matic after conversion
totalStMaticAmountuint256Total StMatic in the contract
totalPooledMaticuint256Total Matic in the staking pool

convertMaticToStMatic​

Returns the StMatic value of any MATIC amount passed to the function

function convertMaticToStMatic(uint256 _amountInMatic)
        public
        view
        override
        returns (
            uint256 amountInStMatic,
            uint256 totalStMaticAmount,
            uint256 totalPooledMatic
        )

Parameters:​

NameTypeDescription
_amountInMaticuint256Amount of MATIC to be convert to StMatic

Returns:​

NameTypeDescription
amountInStMaticuint256Amount of stMatic after conversion
totalStMaticAmountuint256Total StMatic in the contract
totalPooledMaticuint256Total Matic in the staking pool

getToken2WithdrawRequests()​

Returns the list of requestWithdraw attached with a tokenId.

function getToken2WithdrawRequests(uint256 _tokenId)
        external
        view
        returns (RequestWithdraw[] memory)

Parameters:​

NameTypeDescription
_tokenIduint256NFT token ID

Returns:​

NameTypeDescription
requestWithdrawRequestWithdraw[]list of request withdraw

getMaticFromTokenId()​

Returns the amount of MATIC that will be claimed from an NFT token

function getMaticFromTokenId(uint256 _tokenId)
        external
        view
        override
        returns (uint256)

Parameters:​

NameTypeDescription
_tokenIduint256NFT token ID

Returns:​

NameTypeDescription
amountuint256Amount of matic to get after claim the token

Methods​

transfer()​

Moves _amount tokens from the caller's account to the _recipient account.

function transfer(address _recipient, uint256 _amount) returns (bool)
note

Requirements:

  • _recipient cannot be the zero address.
  • the caller must have a balance of at least _amount.
  • the contract must not be paused.

Parameters:​

NameTypeDescription
_recipientaddressAddress of tokens recipient
_amountuint256Amount of tokens to transfer

Returns:​

A boolean value indicating whether the operation succeeded.

allowance()​

Returns the remaining number of tokens that _spender is allowed to spend on behalf of _owner through transferFrom. This is zero by default.

function allowance(address _owner, address _spender) returns (uint256)
note

This value changes when approve or transferFrom is called.

Parameters:​

NameTypeDescription
_owneraddressAddress of owner
_spenderaddressAddress of spender

approve()​

Sets _amount as the allowance of _spender over the caller's tokens

function approve(address _spender, uint256 _amount) returns (bool)
note

Requirements:

  • _spender cannot be the zero address.
  • the contract must not be paused.

Parameters:​

NameTypeDescription
_spenderaddressAddress of spender
_amountuint256Amount of tokens

Returns:​

A boolean value indicating whether the operation succeeded

transferFrom()​

Moves _amount tokens from _sender to _recipient using the allowance mechanism. _amount is then deducted from the caller's allowance.

function transferFrom(
  address _sender,
  address _recipient,
  uint256 _amount
) returns (bool)
note

Requirements:

  • _sender and _recipient cannot be the zero addresses.
  • _sender must have a balance of at least _amount.
  • the caller must have allowance for _sender's tokens of at least _amount.
  • the contract must not be paused.

Parameters:​

NameTypeDescription
_senderaddressAddress of spender
_recipientaddressAddress of recipient
_amountuint256Amount of tokens

Returns:​

A boolean value indicating whether the operation succeeded

increaseAllowance()​

Atomically increases the allowance granted to _spender by the caller by _addedValue

This is an alternative to approve that can be used as a mitigation for problems described here

function increaseAllowance(address _spender, uint256 _addedValue) returns (bool)
note

Requirements:

  • _spender cannot be the the zero address.
  • the contract must not be paused.

Parameters:​

NameTypeDescription
_senderaddressAddress of spender
_addedValueuint256Amount of tokens to increase allowance

Returns:​

Returns a boolean value indicating whether the operation succeeded

decreaseAllowance()​

Atomically decreases the allowance granted to _spender by the caller by _subtractedValue

This is an alternative to approve that can be used as a mitigation for problems described here

function decreaseAllowance(address _spender, uint256 _subtractedValue) returns (bool)
note

Requirements:

  • _spender cannot be the zero address.
  • _spender must have allowance for the caller of at least _subtractedValue.
  • the contract must not be paused.

Parameters:​

NameTypeDescription
_senderaddressAddress of spender
_subtractedValueuint256Amount of tokens to decrease allowance

Returns:​

Returns a boolean value indicating whether the operation succeeded

submit()​

Send MATIC to the StMATIC contract and mints stMATIC to msg.sender. The user has first to approve the amount to the StMATIC contract.

function submit(uint256 _amount, address _referral)
    external
    override
    whenNotPaused
    returns (uint256)

Parameters:​

NameTypeDescription
_amountuint256Amount to submit in MATIC
_referraladdressReferral address

Returns:​

NameTypeDescription
_amountuint256Amount of stMATIC

requestWithdraw()​

Allows users to request withdrawal of an amount of Matic tokens depending on the amount submitted of stMATIC. This will mint a Lido NFT token which can be used later to claim the amount.

 function requestWithdraw(uint256 _amount, address _referral) external override returns returns (uint256);

Parameters​

NameTypeDescription
_amountuint256Amount to withdraw in stMATIC.
_referraladdressReferral address

Returns:​

NameTypeDescription
tokenIduint256The token id

delegate()​

Delegate the deposited tokens into the StMatic contract between Lido's active operators. The tokens are delegated based on the operator's maxDelegationLimit factor.```solidity function delegate()

function delegate() external override

claimTokens()​

Allows users to claim their tokens from the validators. This requires user to have an NFT that was minted during the requestWithdraw transaction.

function claimTokens(uint256 _tokenId) external override

Parameters​

NameTypeDescription
_tokenIduint256NFT Token ID of a pending withdrawal request.

distributeRewards()​

Distribute rewards accumulated by lido validators. 90% of rewards are buffered and redelegated. 10% is distributed between DAO(2.5%), insurance(2.5%), and active operators(5%).

function distributeRewards() external override

withdrawTotalDelegated()​

Allows the NodeOperatorRegistry contract to claim the total amount delegated to a validator share.

function withdrawTotalDelegated(address _validatorShare) external

Parameters​

NameTypeDescription
_validatorShareaddressAddress of the validator share.

rebalanceDelegatedTokens()​

Rebalance the system by withdrawing from the validators that contains more token delegated to them and distributing the withdrawn tokens to validators with less.

function rebalanceDelegatedTokens() external override

calculatePendingBufferedTokens()​

Calculate the total amount stored in all the NFTs owned by StMatic contract

function calculatePendingBufferedTokens()
        public
        view
        returns (uint256 pendingBufferedTokens)

Returns:​

NameTypeDescription
pendingBufferedTokensuint256The total pending buffered tokens

claimTokensFromValidatorToContract()​

Claim and transfer the tokens from a specific validator share contract to the StMATIC contract. This requires a valid Lido NFT token.

function claimTokensFromValidatorToContract(uint256 _tokenId)
        external
        override

Parameters​

NameTypeDescription
_tokenIduint256Token ID of the claim request.

DAO Methods​

note

These methods can be called by DAO-only roles

setFees()​

Set the DAO, operator, and insurance fee.

function setFees(uint8 _daoFee, uint8 _operatorsFee, uint8 _insuranceFee) onlyRole(DAO)

Parameters​

NameTypeDescription
_daoFeeuint8DAO fee in %.
_operatorsFeeuint8Operator fees in %.
_insuranceFeeuint8Insurance fee in %.

setDaoAddress()​

Set a new DAO address

function setDaoAddress(address _address) onlyRole(DAO)

Parameters​

NameTypeDescription
_addressaddressAddress of the DAO.

setInsuranceAddress()​

Set a new insurance address

function setInsuranceAddress(address _address) onlyRole(DAO)

Parameters​

NameTypeDescription
_addressaddressAddress of the insurance.

setNodeOperatorRegistryAddress()​

Set a new node operator registry address

function setNodeOperatorRegistryAddress(address _address) onlyRole(DAO)

Parameters​

NameTypeDescription
_addressaddressAddress of the insurance.

setDelegationLowerBound()​

Set a lower bound amount to delegate to a validator

function setDelegationLowerBound(uint256 _delegationLowerBound) onlyRole(DAO)

Parameters​

NameTypeDescription
_delegationLowerBounduint256Lower bound amount.

setRewardDistributionLowerBound()​

Set a lower bound for distributing reward to validators

function setRewardDistributionLowerBound(uint256 _rewardDistributionLowerBound) onlyRole(DAO)

Parameters​

NameTypeDescription
_rewardDistributionLowerBounduint256Lower bound reward amount.

setPoLidoNFT()​

Set PoLidoNFT address

function setPoLidoNFT(address _poLidoNFT) onlyRole(DAO)

Parameters​

NameTypeDescription
_poLidoNFTaddressPoLido NFT address.

setFxStateRootTunnel()​

Set fxStateRootTunnel address

function setFxStateRootTunnel(address _fxStateRootTunnel) onlyRole(DAO)

Parameters​

NameTypeDescription
_fxStateRootTunneladdressFxStateRootTunnel address.

setSubmitThreshold()​

Set submit threshold for users

function setSubmitThreshold(uint256 _submitThreshold) onlyRole(DAO)

Parameters​

NameTypeDescription
_submitThresholduint256Threshold amount for submit.

flipSubmitHandler()​

Set the value of submit handler to false

function flipSubmitHandler() external override onlyRole(DAO)

setVersion()​

Set contract version

function setVersion(string calldata _version) onlyRole(DEFAULT_ADMIN_ROLE)

Parameters​

NameTypeDescription
_versionstringVersion of the contract.

Admin Methods​

note

This method can be called by ADMIN-only roles

pasue()​

Allows an authorized user with PAUSE ROLE to pause the contract.

function pause() external onlyRole(PAUSE_ROLE);

unpasue()​

Allows an authorized user with UNPAUSE ROLE to unpause the contract.

function unpause() external onlyRole(PAUSE_ROLE);