# 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 participant 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 epoches (~3 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 from: https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/lib.rs

- 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 from: https://github.com/near/core-contracts/blob/master/staking-pool/src/lib.rs

### Key functions

- Functions for users
- Stake
- Typically the user stakes his $NEAR tokens via the `deposit_and_stake` function.
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/stake.rs#L21
- Unstake
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/stake.rs#L70
- 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
- Withdraw
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/stake.rs#L37
- Withdraw unstaked $NEAR to user's wallet.
- 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
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/epoch_actions.rs#L28
- 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
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/epoch_actions.rs#L104
- Epoch update rewards
- This function will be called in each epoch for every validators that LiNEAR has staked on to update staking rewards.
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/epoch_actions.rs#L104
- Epoch withdraw
- This function will be called to withdraw unstaked $NEAR from validators to fulfill users' unstake/withdraw requests.
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/epoch_actions.rs#L104
- Functions of NEP141 token
- https://github.com/linear-protocol/LiNEAR/tree/main/contracts/linear/src/fungible_token
- Files in this folder define NEP141 related functions
- Functions for manager/owner
- These are privileged functions for manager/owner to manage validator list and update protocol settings.
- Owner
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/owner.rs
- Validator list management
- https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/validator_pool.rs#L471-L587

### State variables
All state variables are defined in https://github.com/linear-protocol/LiNEAR/blob/main/contracts/linear/src/lib.rs#L56 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 privilleged 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 of 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: https://github.com/near/core-contracts/tree/master/whitelist

## Pause/Unpause the contract
In case of an emergency iccident 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 : https://docs.linearprotocol.org/automatic-staking-optimization