LiskHQ · matjazv · Apr 29, 2024 · Apr 24, 2024 · Apr 24, 2024 · Apr 24, 2024
diff --git a/README.md b/README.md
@@ -17,7 +17,6 @@ Additionally, it also includes various deployment scripts that are integral for
   - [Deployment Directory Folder](#deployment-directory-folder)
   - [Deployment of L2 Lisk Token](#deployment-of-l2-lisk-token)
   - [Transferring Lisk Tokens After Smart Contracts Deployment](#transferring-lisk-tokens-after-smart-contracts-deployment)
-  - [Lisk L2 Staking](#lisk-l2-staking)
   - [Smart Contract Ownership](#smart-contract-ownership)
 - [Contributing](#contributing)
 - [Security](#security)
@@ -108,14 +107,6 @@ The distribution of newly minted Lisk tokens takes place in accordance with the
 
 The process ensures that each address specified in the json files receives the designated amount of tokens accurately. Any remaining Lisk Tokens, those not allocated to the addresses listed in the files, are then transferred to the [Claim smart contract](src/L2/L2Claim.sol). This systematic distribution is critical for ensuring that the tokens are correctly assigned to their intended recipients across the different network layers as part of the project's requirements.
 
-### Lisk L2 Staking
-Staking L2 tokens creates additional utility of L2 Lisk token by allowing user to stake an amount of token for a certain period of time allowing them to earn daily rewards and contribute to Governance.
-
-Implementation of L2 staking functionality is separated into;
-- `L2LockingPosition` contract represents staking positions as an implementation of ERC721 (NFT) interface.
-- `L2Staking` contract manages interactions with `L2LockingPosition` contract. It restricts manipulation of staking positions represented by `LockingPostion` structure to the creator role.
-- `L2Reward` contract exposes the public API to stakers, enabling them to lock funds, manipulate existing position they own and claim rewards.
-
 ### Smart Contract Ownership
 
 Some of the smart contracts in this project are designed to be `ownable`, meaning they have an assigned owner. This ownership allows for certain privileges and actions. For instance, in the case of upgradable smart contracts like the [Claim smart contract](src/L2/L2Claim.sol), the owner has the ability to upgrade the contract. This feature is crucial for making improvements or fixes to the contract after deployment.

diff --git a/documentation/diagrams/interaction_reward_and_dependencies.png b/documentation/diagrams/interaction_reward_and_dependencies.png
diff --git a/documentation/diagrams/l2lockingposition_api.png b/documentation/diagrams/l2lockingposition_api.png
diff --git a/documentation/diagrams/l2reward_external_account_api_and_events.png b/documentation/diagrams/l2reward_external_account_api_and_events.png
diff --git a/documentation/diagrams/l2reward_owner_api_and_events.png b/documentation/diagrams/l2reward_owner_api_and_events.png
diff --git a/documentation/diagrams/locking_position.png b/documentation/diagrams/locking_position.png
diff --git a/documentation/staking-governance.md b/documentation/staking-governance.md
@@ -4,8 +4,8 @@
 
 In general, staking and governance in Lisk is inspired by the veToken Model and [this staking proposal for the Arbitrum DAO](https://snapshot.org/#/arbitrumfoundation.eth/proposal/0xf22530295daee96dffd7f70854475c06216a4d3594929672f71c12bf638bb0c8). The basic idea is that token holders have the option to lock their tokens in Lisk for a duration between 2 weeks and 2 years in return for:
 
-- **voting power** depending on the locked amount with the option of a boost for longer paused unlocking countdown
-- **staking rewards** depending on the locked amount and locking duration
+- **voting power** depending on the locked amount with the option of a boost for longer paused unlocking countdown.
+- **staking rewards** depending on the locked amount and locking duration.
 
 This design with selectable locking duration helps to align token holders with the long term success of the Lisk project.
 
@@ -83,3 +83,6 @@ For creating a proposal or voting on a proposal, the user is interacting with th
 ![Queueing](diagrams/queue.png)
 
 If a proposal has an attached execution, e.g. a transfer of some treasury funds, and the proposal passed, then the proposal must be queued and then executed. For this, a user (this can be any user) must interact with the Governor contract. This one is forwarding the queue/execute operation to the Timelock Controller contract, and the Governor contract additionally emits events which Tally uses for indexing. The Governor contract is the only account that is allowed to queue proposals at the Timelock Controller. As all executions are eventually executed by the Timelock Controller, contracts owned by the Lisk DAO must be owned by the Timelock Controller, and the DAO treasury must be held by it as well.
+
+### Implementation of Lisk Staking
+[See Lisk Staking implementation page](./staking.md)
diff --git a/documentation/staking.md b/documentation/staking.md
@@ -0,0 +1,65 @@
+# L2 Lisk Staking
+
+Staking L2 tokens creates additional utility of L2 Lisk token by allowing user to stake (Locking Position) an amount of token for a certain period of time allowing them to earn daily rewards and contribute to Governance.
+
+## Implementation
+
+Implementation of L2 staking functionality is separated into,
+
+- `L2LockingPosition` contract maintains locking positions and allows owner to manipulate their positions. The contract is an implementation of ERC721 based NFT and interacts with L2VotingPower contract to adjust the voting power of the owner of the locking position when consumed by L2Staking contract.
+
+- `L2Staking` contract manages and controls access to core staking functionality allowing “creators” to lock amounts and manipulate them. The contract consumes `L2LockingPosition` to modify locking positions and the relevant voting power of their owner.
+
+- `L2Reward` contract interacts with `L2Staking` contract by mirroring its API enabling its users to interact with the entire set of staking functionalities. Moreover, it manages rewards of locking positions, however it only enables rewards and allows manipulation of locking positions created via `L2Reward` contract. Rewards can only be claimed against locking positions created by `L2Reward` not the ones created via `L2Staking` contract.
+
+- `L2VotingPower` contract is an implementation of `ERC20Votes` token standard that maintains the voting power of an account.
+
+
+### Structure of a Locking position
+A locking position (or a stake) is represented as a custom data structure containing:
+
+![Structure of a Locking position](diagrams/locking_position.png)
+
+| Property              | Type      | Description                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| creator               | `address` | Address of the creator, it could only be one from the set of creators that are added to the list of creators of `L2Staking` contract by its owner. This can either be the staking contract or the reward contract, as staking contract is the only contract allowed to modify a position, it uses this property to determine who should be allowed to trigger a modification. |
+| amount                | `uint256` | Amount to be locked.                                                                                                                                                                                                                                                                                                                                                          |
+| expDate               | `uint256` | The expiration date, i.e., the day when the locked amount becomes claimable for the user.                                                                                                                                                                                                                                                                                     |
+| pausedLockingDuration | `uint256` | Remaining duration in days till the expiry once a paused locking position is resumed. It is set to zero if the locking position is not paused.                                                                                                                                                                                                                                |
+
+### Identifying a Locking Position
+`L2LockingPosition` contract maintains a collection of locking positions against each user and uniquely identifies them with an identifier of type `uint256`.
+
+### L2Reward Contract
+#### Events emitted on interactions
+`L2Reward` communicates changes to state made by the contract or other contracts it consumes through events:
+
+| Contract            | Event                     | Description                                                                                                                                                                                   |
+| ------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `L2Reward`          | `RewardsAdded`            | Emitted when the owner of the L2Reward contract adds funds for rewarding locking positions.                                                                                                   |
+| `L2Reward`          | `RewardsClaimed`          | Emitted when rewards for a locking position are claimed. Note that this happens automatically when a locking position is modified.                                                            |
+| `L2LockingPosition` | `LockingPositionCreated`  | Emitted when an external account creates a locking position.                                                                                                                                  |
+| `L2LockingPosition` | `LockingPositionModified` | Emitted when an external account modifies a locking position.                                                                                                                                 |
+| `L2LockingPosition` | `Transfer`                | Emitted when a locking position is transferred to another account.                                                                                                                            |
+| `L2VotingPower`     | `Transfer`                | Emitted when external account creates or modifies a locking position, as the parameters of a locking position impact its owner's voting power by minting or burning some voting power tokens. |
+
+#### API accessible to external user and Events
+The diagram highlights the public API accessible to external accounts and how creation and manipulations of locking positions consumes other smart contracts and the relevant events that are emitted.
+
+![API accessible to external user and Events](diagrams/l2reward_external_account_api_and_events.png)
+
+#### API accessible to the owner of L2Reward contract and Events
+L2Reward contract is ownable and allows the contract owner to add funds for rewarding locking positions. Its owner can allocate new funds and unused rewards accumulated due to reward capping for a certain duration.
+
+![API accessible to the owner of L2Reward contract and Events](diagrams/l2reward_owner_api_and_events.png)
+
+## L2LockingPosition Contract
+
+This contract exposes the public API to retrieve information about locking positions against an owner.
+
+![API L2LockingPosition](diagrams/l2lockingposition_api.png)
+
+# Representing Time
+
+Contracts involved in L2 Lisk staking maintains (UNIX epoch) time at the granularity of a day, instead of seconds.
+The day 19740, will be 19740 x 60 x 60 x 24 i.e. 1705536000 epoch seconds, any interactions at other higher-level environment must convert days to epoch time.