Contract Overview

LiNEAR Contract

The source code can be found here: https://github.com/linear-protocol/LiNEAR

Description

LiNEAR Protocol is a non-custodial liquid staking protocol built on NEAR blockchain. You can stake $NEAR via LiNEAR Protocol, receiving PoS staking rewards same as every other $NEAR staker, but also receive liquid $LiNEAR token which could be used in DeFi protocols. Furthermore, you can unstake your $LiNEAR and receive back $NEAR instantly with no waiting time, while a small portion of fees will be charged.

The price of $LiNEAR goes up each epoch with staking rewards being accrued into the underlying staked $NEAR.

Use Case

• Stake $NEAR:

  • A user who wants to participate in NEAR staking can stake(deposit) his $NEAR to LiNEAR contract and get back $LiNEAR tokens. The $LiNEAR tokens are standard NEP141 tokens so that he can transfer/sell them freely.

• Unstake $LiNEAR:

  • If the user wants to exit staking and get his $NEAR back with his rewards together, he can unstake(withdraw) $NEAR by burning $LiNEAR tokens. There are two approaches he can take:

    • Instant Unstake: Swap $LiNEAR tokens for $NEAR instantly from a liquidity pool in ref.finance. This way the user needs to bear transaction fees and slippage, however he can get $NEAR back immediately without any delay.

    • Delayed Unstake: If the use doesn't want to pay for any swap fees he can choose delayed unstake. Delayed unstake will make LiNEAR contract to actually unstake from underlying validators so that the exchange rate can always be guaranteed. However there is a delay between initiating the unstake and actual receiving the $NEAR back. Typically it takes 4 epochs (~2.5 days).

Contracts

• LiNEAR

  • There is only one contract of LiNEAR protocol. It handles stake/unstake from users and it's also the NEP141 token contract of $LiNEAR token. You can find the entrance of this contract here

• Staking Pool

  • LiNEAR contract will call staking pool contracts of each validator to perform actual stake/unstake actions. You can find the implementation of staking pool contract here

Key Functions

• Functions for Users

  • Stake

    • Typically the user stakes his $NEAR tokens via the deposit_and_stake function.

    • source code

  • Unstake

    • Note that unstake will not transfer $NEAR to the user, the funds remain in the LiNEAR contract until user explicitly withdraws them using the function below

    • source code

  • Withdraw

    • Withdraw unstaked $NEAR to user's wallet.

    • source code

• Functions for Epoch Operator

  • LiNEAR contract will not do actual stake/unstake actions against staking pools for every user action. Instead it will buffer all the requests for one single epoch and fire stake/unstake requests at once. The following functions are called by an operator account per epoch to interact with underlying staking pools.

  • Epoch Stake

    • If there are more staking requests than unstaking requests, this function will be called at each epoch to perform actual staking to validators

    • source code

  • Epoch Unstake

    • If there are more unstaking requests than staking requests, this function will be called at each epoch to perform actual unstaking from validators

    • source code

  • Epoch Update Rewards

    • This function will be called in each epoch for every validators that LiNEAR has staked on to update staking rewards.

    • source code

  • Epoch Withdraw

    • This function will be called to withdraw unstaked $NEAR from validators to fulfill users' unstake/withdraw requests.

    • source code

• Functions of NEP141 token

  • Files in this folder define NEP141 related functions

  • source code

• Functions for Manager/Owner

  • These are privileged functions for manager/owner to manage validator list and update protocol settings.

  • Owner

    • source code

  • Validator list management

    • source code

State Variables

All state variables are defined here and are detailed commented.

Privileged Roles

Owner

Owner role has the authority to config key parameters (including managing other roles, set treasury account Id and pause/unpause the contract) in the protocol and can also upgrade the contract. Currently the owner is set to the LiNEAR DAO (linear.sputnik-dao.near)

Manager

Managers are able to manage validators on LiNEAR in the following ways:

• add validators

• remove validators

• update weight of validators

• update base stake amounts of validators (only used by stake war delegation)

• drain a validator (explained later)

Operator

Operator is not a privileged role, it's just a normal NEAR account that we used in our off-chain worker to periodically call epoch actions of LiNEAR. The operator account ID is operator.linear-protocol.near.

Draining a Validator

Draining enables us to manually unstake all delegated NEAR from a specific validator, typically this is used when a validator has been offline for a while or it raised its fee to 100%. When drain_unstake is called by the manager, all staked NEAR will be unstaked from that validator, and after 4 epochs drain_withdraw needs be called to withdraw the funds back to the pending pool, which then could be distributed to other validators.

Validator Whitelist

The NEAR foundation uses a specific contract (lockup-whitelist.near) to maintain the whitelist of the staking pool contracts account IDs that are approved by NEAR Foundation which lockup accounts can delegate to. Please find the details here

Pause/Unpause Contract

In case of an emergency incident happened, the contract can be paused by the owner DAO to stop all user interactions and it can be unpaused later when the issues are resolved. The functionalities that could be paused includs:

• All epoch actions (stake, unstake, withdraw, update rewards)

• User deposit, stake, unstake and withdraw

• Changing of manager role

• Changing of treasury

• All validator-related actions (add, remove, update weight)

• LiNEAR token transfers are disabled

Validator Selection Algorithm

Please refer to the Automatic Staking Optimization doc.