second-state / linear-timelock-smart-contract

Solidity smart contract which disburses ERC20 tokens linearly, over a specific period of time (all values are dynamic and are set by the contract owner)

Linear timelock smart contract

Solidity smart contract which disburses ERC20 tokens linearly, over a specific period of time (all values are dynamic and are set by the contract owner)

How to deploy this linear timelock smart contract

Step 1

• Create a brand new account (a new private/public key pair); and do not share the private key with anyone.
• Ensure that the aforementioned account is selected in your wallet software i.e. MetaMask or similar.
• Ensure that your wallet software is connected to the correct network.
• Compile the LinearTimelock.sol contract using Solidity 0.8.11 via the Remix IDE. Using version 0.8.11 is important because it provides overflow checks and is compatible with the version of SafeMath which the contract uses.

Step 2

• Ensure that Remix environment is set to "Injected Web3" so that the execution environment is provided by your MetaMask (or similar) wallet software (which must currently be on the Ethereum mainnet with your new owner's account selected).

• As the contract owner, deploy the LinearTimelock.sol. The only parameter required is the address of the ERC20 contract for which we are locking up tokens for.

Step 3

• Perform the setTimestamp function and pass in the two required parameters:

1. the _cliffTimePeriod - the amount of seconds from now until when the linear unlocking (release) period begins
2. the _releaseTimePeriod - the entire amount of seconds from now until when the unlocking period ends (this is inclusive of the _cliffTimePeriod)

For example if you want to:

• lock the tokens for 1 day
• then (after 1 day has passed) commence releasing the tokens linearly over an additional 2 day period

The _cliffTimePeriod will be 86400 (1 day represented in seconds) The _releaseTimePeriod will be 259200 (3 days represented in seconds).

Step 4

• Check the timestamp variables are correct, before transferring any tokens. There is still an opportunity to abandon this contract if any mistakes have been made with the timestamps.

timestampSet

• Check that the timestampSet variable is true

initialTimestamp

• Check the initialTimestamp variable, and confirm its value in proper date format by using an online epoch to date converter

For example, the value in the above image, 1642993044 is equivalent to Monday, 24 January 2022 12:57:24 GMT+10:00

cliffEdge

• Check the cliffEdge variable, and confirm its value is what your lockup period is intended to be.

For example, the value in the above image, 1643079444 is equivalent to Tuesday, 25 January 2022 12:57:24 GMT+10:00 (which is exactly one day ahead of the initialTimestamp which is correct)

releaseEdge

• Check the releaseEdge variable, and confirm its value is what your release period is intended to be.

For example, the value in the above image, 1643252244 is equivalent to Thursday, 27 January 2022 12:57:24 GMT+10:00 (which is exactly 2 days ahead of the cliffEdge which is the same as being 3 days ahead of the initialTimestamp, which is correct).

Checking the associated ERC20 contract

• First of all, please check to make absolutely sure that the ERC20 contract associated with this linear timelock contract is correct. This can be done by calling the erc20Contract variable, as shown below.

Allocating user tokens into the timelock contract

Tokens can be allocated to users one at a time using the depositTokens function, as shown below.

Tokens can also be allocated in bulk using the bulkDepositTokens function.

Always keep an exact record of how many tokens (sum total of all ERC20 tokens) which you allocated to the users. This sum total figure is required for the next step (and ensures that there will be the exact amount of tokens in the linear timelock contract to service all of the users, who will be performing the unlock).

Transfer ERC20 tokens to the linear timelock contract

• Check that the amounts of tokens allocated to each address, in the previous step, are correct. If there are any issues, do not transfer any ERC20 tokens to the contract address. At this stage if there are any issues you could abandon this contract instance before tokens of real value are sent/locked.

• Once completely satisfied with all of the above, transfer the appropriate amount of ERC20 tokens (i.e. the sum total of all ERC20 tokens which you allocated to the users in the previous step) to the linear timelock smart contract's address.

• Confirm that these tokens have been transferred by pasting the linear timelock contract's address into the ERC20 contract's balanceOf function, as shown below.

Finalize owner participation

• Once all allocations have been made and the ERC20 tokens have been transferred into the linear timelock contract, the owner can call the linear timelock contract's finalizeAllIncomingDeposits() function. This makes the linear timelock non-custodial, whereby the contract owner has no ability to alter token amounts and so forth. The operation of the linear timelock contract is purely based on the math in the transferTimeLockedTokensAfterTimePeriod function from this point forward.

How to use this linear timelock DApp

The smart contract is deployed and then coupled with the official linear timelock user interface. Please follow the instructions in the linear timelock user interface's README.md

linear-timelock-smart-contract's Issues

Need the ability to withdraw entire balance after releasePeriod

At present the withdraw request functionality calculates wei per second and uses that to disburse the correct amount of tokens (depending when the request is made; between the cliffEdge and the releaseEdge).

This calculation does not serve the purpose of when a user calls the request functionality after the releasePeriod has elapsed. A user should just be allowed to withdraw any amount up to their balance. No calculation is required for this.

The contract needs to be updated with an if else statement to differentiate these two conditions i.e. is the request made between the cliffPeriod and releasePeriod (requires calculation) or is the request made after the releasePeriod (whole balance is available).