Kin Foundation Vesting Trustee Smart Contract

Preface

In our token distribution event, which was held in September, we issued 10 trillion KIN. As stated in our whitepaper (Chapter 6), 60% of these tokens (i.e., six trillion) will be under the purview of the Kin Foundation, locked under the Kin Rewards Engine schema (whose initial version we have recently released a request for comments for), and used strategically to grow the Kin Ecosystem and fund the operations of the Foundation. The Kin Foundation’s allocation will be used for three purposes:

1. Administration of the Kin token supply and Kin Rewards Engine
2. Marketing and strategic partnerships
3. Any additional operational costs

20% of the remaining reserve will be unlocked and distributed every year to the Kin Foundation in perpetuity.

In order to fulfill this requirement we are happy to introduce the Kin Foundation vesting trustee smart contract, which will soon be deployed as a smart contract on the Ethereum blockchain. This smart contract will be in charge of releasing funds to the foundation according to a vesting schedule and will provide added visibility for the operation of the foundation. The code has been submitted as a pull request over on the Kin token GitHub repository and is open to the public.

In the following article I will detail the tidbits of the contract and explain select sections.

Note the following snippets is Solidity code. At the time of writing this post, GitHub doesn’t support Solidity syntax highlighting, so I’ve gone ahead and displayed them as Javascript for better readability.

Solidity

The contract is written in Solidity 0.4.15 and supports ERC20 standard tokens. It uses the following libraries for additional functionality:

1. BasicToken.sol: Basic ERC20 functionality e.g. balance, transfer, etc.
2. TokenHolder.sol: Allows owner to transfer away accidentally sent ERC20 tokens.

In addition, we’ve used libraries from OpenZeppelin/zeppelin-solidity offered by OpenZeppelin (which have also reviewed our token and sale contracts in preparation for the token distribution event), more specifically:

1. SafeMath.sol: Safe math operations
2. Ownable.sol: Basic authorization control functions and permissions

Events

The contract emits events upon initializing the vesting schedule, unlocking vested tokens and revoking the contract. This is smart contract development standard and will be used in the alpha product which is planned to be launched early this December.

Modifiers

The contracts also use Solidity modifiers to make sure grants and token unlocking doesn’t happen for the wrong address or time.

Vesting Schedule Length and Grant Frequency

The grants are fully visible and hard coded, and are spread out over 60 years. While the whitepaper states the grants will be distributed in perpetuity — the amount starts to be negligible after so many years — less than 0.00004% of the entire allocation. We came to the conclusion that hard coding the grants in the contract is much safer and clearer than calculating them whenever grant functions are called.

In addition, the Kin Foundation is able to unlock its vested tokens every day. Otherwise, if we would want to turn on the Rewards Engine in between these periods, we would’ve had to wait for the next period to end before the foundation will have enough funds to operate.

Annual Grant Calculation

The following short piece of Javascript code is not part of the contract but was used to generate the annual grants values. It makes use of the popular bignumber.js arbitrary-precision arithmetic library. It prints a JSON number array, where each element, along with its location in the array, represents that year’s grant, which is 20% of the remaining token allocation. The last year (60) includes all remaining unvested Kin that should be vested in that year and in all the following years. The output is hard coded in the contract, as can be seen above.

Construction

Deploying the contract involves stating the token contract and grantee wallet address, which is the Kin Foundation.

Revoking

The contract is revocable (i.e., it can be destroyed, and all remaining unvested tokens are returned to the contract owner). Currently the owner is a multisig wallet managed by Kik, intended for the Kin Foundation. Its owners were created using a separate set of hardware wallets, which officially belong to the Kin Foundation. We should note that this was also noted by OpenZeppelin in their review. This is temporary and is necessary since the vesting contract is subject to the authority of the Kin Foundation itself. It might be totally replaced in the future with an updated version (e.g., adding the Kin Reward Engine distribution to an upgraded contract).

Granting

Granting the tokens requires a stated vesting start time to initialize the vesting schedule. We will set this time to the end of the token distribution event, which was on Sep. 26th, 2017 at 07:14 AM UTC.

Unlocking Vested Tokens

When the grantee, the Kin Foundation, will need to unlock its vested tokens, it will call this function. It calculates the current amount of vested tokens and how much of that was already transferred to the grantee, then transfers the difference.

Calculating Daily Vested Tokens

Calculating the tokens is based on the following algorithm:

1. Sum all annual grants from previous years.
2. Calculate the amount of days passed since the beginning of this year: (a) Calculate the amount of days passed since the beginning of the entire grant, then (b) Subtract the amount of years that have passed in full from it. For example: If two years and 12 days have passed since vesting had started (total 742 days), then the calculation that will take place will be: 742 –2 * 365 = 12 where 742 is the current day since the grant has started.
3. Take this number and divide it by 100 to get the percentage of that year that should be vested (e.g., 12 / 100 is the same as 12%).
4. Multiply this value by this year’s grant (e.g., for the second year the annual grant is 9.6e+29, so the vested tokens for the current year up to this day is 9.6e+29 * 12 / 100 = 1.1520000000000001e+29 ).
5. Add this value to the sum of annual grants from previous years.
6. Return the result.

In the calling function — unlockVestedTokens() — This value will calculate the amount of funds that were already transferred, and then transfer the remaining difference (e.g., if the Kin Foundation attempted to unlock tokens a day before, then only one day worth of funds will be transferred). This is used in order to prevent any possibility of unlocking more tokens than allowed.

Tests

Like in our other smart contracts, we used the Truffle framework for heavily testing this one. There are over 1500 tests, spanning multiple aspect of the contract: From accurate vesting calculation dependent on time to correct event emission to possible revocation scenarios.

Here is an interesting case (unlike the above Solidity code, this one is Javascript) - This table test checks the different vesting calculations at multiple times each year during the 60 years of vesting. It also makes sure no additional KIN is unlocked during subsequent unlock attempts every day:

Conclusion

The deployment of the vesting trustee smart contract is an important and mandatory milestone prior to the launch of the Kin Reward Engine. We will be deploying this contract in the following days once we finish auditing and testing it. You are welcome to review and comment on the contract over on GitHub.

I hope this article was both educating and interesting. Please let us know what you think.