KLAY Staking Protocol

This repository contains the core smart contracts and their tests for Swapscanner's $KLAY staking protocol.

The Solidity contracts in this repository are organized into two main contracts, as described in the Inheritance Structure section.

The deployment process for these contracts is as follows:

1. The Klaytn Foundation will deploy either CnStakingContract or CnStakingV2 (collectively referred to as CNStaking).
2. Deploy either CNStakedKLAYV1 or CNStakedKLAYV2 (referred to as CNStakedKLAY) based on the chosen CNStaking.
3. Call CNStaking.submitAddAdmin(CNStakedKLAY) to make the deployed CNStakedKLAY an admin of CNStaking.
4. Set the quorum requirement to 0x1 by calling CNStaking.submitUpdateRequirement(0x1).
5. Update the reward address to CNStakedKLAY by calling CNStaking.submitUpdateRewardAddress(CNStakedKLAY).
6. (Optional) Remove other admins one by one.

Reward Issuance

CNStakedKLAY will serve as the (sole) admin of CNStaking, responsible for receiving and distributing rewards issued to itself, as well as managing the staked $KLAY.

Rewards will be automatically issued by increasing the reward address's balance internally by Klaytn. This process will not invoke the receive() fallback function, as Klaytn will only increase the balance.

The sweep() function is responsible for receiving and distributing rewards. It will be automatically executed during most operations, including stake(), unstake(), and transfer(). This ensures that rewards are automatically staked and recursively distributed to users based on their "shares".

Share Issuance and Reward Distribution

When a user stakes their $KLAY, CNStakedKLAY issues "shares". These shares do not directly represent a 1:1 ratio with $KLAY. Instead, the entire staked $KLAY pool is distributed in proportion to the shares owned by users. This approach enables automated reward distribution as staking rewards are generated.

Voting with Staked KLAY

There are two distinct voting systems, with one currently in place and the other to be introduced later:

1. Klaytn Governance Council voting (currently in place): In this system, only governance council members, such as Swapscanner, can cast their votes on proposals.
2. CNStakedKLAY voting (to be introduced later): This system, enabled by CNStakedKLAY extending ERC20Votes, will allow anyone who has staked their $KLAY to participate in voting on proposals.

Swapscanner, as a member of the Klaytn Governance Council, has the power to vote. However, to promote decentralization, Swapscanner plans to base its vote on the outcome of the yet-to-be-implemented CNStakedKLAY voting system. This approach will allow users who have staked their KLAY to influence Swapscanner's voting decisions within the Klaytn governance process once the CNStakedKLAY voting system is introduced.

Inheritance Structure

• CNStakedKLAYV2
  • ProxyStakedKLAYUnstakeable
    • ProxyStakedKLAY
      • IProxyStakedKLAY
      • FeeCalculator
      • CNStakingInterface
      • Ownable
      • ERC20ProgrammaticBalanceStats
        • ERC20ProgrammaticBalance
          • ERC20VotesCustomBalance
            • IVotes
            • ERC20Permit
  • CNStakingV2Interface (or CNStakingV1Interface for use with CnStakingContract instead of CnStakingV2)

Contracts

| Contract Name | type | Feature | | ------------------------------------- | ------------------- | ----------------------------------------------------------------- | | crytic/echidna/*.sol | test | Echidna fuzz tests. | | test/**/*.sol | test | Contains mockup contracts for unit and end-to-end tests. | | cnstakinginterfaces/*.sol | abstract contract | Contains logic for interacting with CNStaking. | | external/**/*.sol | mixed | External libraries. | | interfaces/*.sol | interfaces | Interfaces. | | libraries/EtherStrings.sol | library | Converts uint256 wei amount to human-friendly ether strings. | | libraries/Fonts.sol | library | Includes base64 encoded WOFF2 fonts. | | libraries/SharesMath.sol | library | Math for share-amount calculation. | | libraries/TimestampStrings.sol | library | Converts uint256 timestamp into human-friendly date-time string. | | CNStakedKLAYV1 | deployable contract | Entrypoint contract for use with CnStakingContract | | CNStakedKLAYV2 | deployable contract | Entrypoint contract for use with CnStakingV2 | | ERC20ProgrammaticBalance.sol | abstract contract | ERC20 + "share"-based virtual balance management. | | ERC20ProgrammaticBalanceStats.sol | abstract contract | Emit Stat() event for APR tracking purpose. | | ERC20VotesCustomBalance.sol | abstract contract | ERC20Votes + ERC20ProgrammaticBalance support. | | FeeCalculator.sol | abstract contract | Manages and calculates fee amounts. | | ProxyStakedKLAY.sol | abstract contract | Manages staking. | | ProxyStakedKLAYClaimCheck.sol | deployable contract | NFT (ERC721) that will be issued for each unstaking requests. | | ProxyStakedKLAYUnstakeable.sol | abstract contract | Unstaking logic for ProxyStakedKLAY. |

Useful yarn scripts

$ yarn lint
$ yarn test
$ yarn slither
$ yarn echidna:e2e
$ yarn echidna:e2e-erc20-programmatic-balance
$ yarn coverage
$ yarn gas-report
$ yarn compile
$ yarn clean

Security Audits

This project is currently undergoing security auditing. Reports will be available here.

Licenses

The primary license for Swapscanner KLAY Staking is the GNU General Public License v3.0 or later (GPL-3.0-or-later), see LICENSE. However, some external files are under different licenses.

• contracts/external/BokkyPooBahsDateTimeLibrary.sol is imported from here and licensed under MIT (as indicated in their SPDX headers).
• contracts/external/klaytn/cnstaking/*.sol are imported from here and licensed under GNU Lesser General Public License v3.0 (as indicated in their LICENSE).
• contracts/external/klaytn/cnstakingv2/*.sol are imported from here and licensed under GNU Lesser General Public License v3.0 only (as indicated in their SPDX headers).