Repository navigation
Description
Module Development Task
Vesting Escrow Wallet
| Module Type | Bounty Payout | Completion deadline |
|---|---|---|
| Wallet | 5, 000 POLY | 14 days to complete once task is confirmed by external developer(s). |
Short Summary
As an Issuer, I can program an automated token vesting schedule for employees and/or affiliates so that Tokens get delivered to their wallets as contractually defined.
This would be a smart contract that the issuer can send tokens to and then select the address that would be able to withdraw them according to their specific vesting schedule.
Bounty Requirements
- Module specs are fulfilled
- Module is implemented using appropriate module interface
- Module is tested with >95% branch coverage
- Module is delivered before deadline
- Module does not present any bugs.
- 14 days to complete module from developers initial start date.
IMPORTANT: Please work from the development-1.5.0 branch instead of master.
Module Details and Specs (Wireframe)
Wireframe Link: https://www.lucidchart.com/invitations/accept/450646a3-5af0-42b5-b155-de5ec94232d4
Assumptions & User/Issuer Stories
-
As an issuer I want to be able to add a module for vesting schedule to my STO
-
As an issuer I want to add vesting schedules to employees / affiliates I have minted tokens so that I can incentivize them for the long term
-
As an issuer I want to add vesting schedules to employees / affiliates I have not minted tokens so that I can incentive new employees / affiliates for the long term
-
As an issuer I want to be able to create a template of a vesting schedule so that I can easily apply them to each of the employees / affiliates
-
As an issuer I want to be able to bulk add vesting schedules for each of my employees / affiliates so that I don't have to manually do it for each individual one
-
As an issuer I want to be able to void a vesting schedule so that I can stop the automated vesting if an employee / affiliate leaves
-
As an issuer I want to be able to add multiple vesting schedules for each employee / affiliate so that I can issue out tokens as bonus and continue to incentivize them for the long term
-
As an issuer I want to be able to view all my vesting schedules and it's progress so I can have a quick overview on how much tokens each of my employees / affiliates have
Activity
gitcoinbot commentedon Sep 21, 2018
Issue Status: 1. Open 2. Started 3. Submitted 4. Done
This issue now has a funding of 5000.0 POLY (749.5 USD @ $0.15/POLY) attached to it.
gitcoinbot commentedon Sep 21, 2018
Issue Status: 1. Open 2. Cancelled
Work has been started.
These users each claimed they can complete the work by 4 months, 2 weeks ago.
Please review their action plans below:
1) shanefontaine has been approved to start work.
The following are steps that will be taken to complete this task:
The following are questions that I have related to the task:
Note: I have written a very similar contract before and have experience with this kind of smart contract.
Learn more on the Gitcoin Issue Details page.
satyamakgec commentedon Sep 22, 2018
@shanefontaine Sounds like a plan from your side.
Answers to your queries -
Employees/Affiliates can pull the tokens when they are available.
As per our current ecosystem, we don't have the upgradeable modules so I prefer you can follow the same standard as we have in our existing module ecosystem.
Vesting schedule is variable for some employees it will be 4 yrs some for 2 yrs and some for 1 yr or 5 yrs and according to that they have different disbursement rate quaterly, halferly, Annualy etc.
Yes, vesting tokens have the cliff you can check the specs. In specs, it is written as
Vesting Frequency.If you have more queries then please let me know.
shanefontaine commentedon Sep 22, 2018
@satyamakgec Am I approved and allowed to proceed on this work?
satyamakgec commentedon Sep 23, 2018
@CPSTL please put some light here.
CPSTL commentedon Sep 23, 2018
@shanefontaine Please let me know if you have any questions as you work towards this task.
shanefontaine commentedon Sep 26, 2018
@CPSTL @satyamakgec A few questions:
Business Logic
assumptionsand flow diagram seem to show two different answers to this question.Assumptions & User/Issuer Storiespost above?Assumptions & User/Issuer Storiesbe done off chain? To me, it makes more sense to create the template off-chain and simply pass it in for each user, as opposed to saving an unknown number of states on-chain. I can go either way, so let me know.assumptionsnumber (5) states "Beneficiary may receive tokens automatically or retrieve them from the Vesting Smart Contract". How would they automatically receive them? Is an admin allowed to push tokens out to the user?use casesnumber (3) states "Employee leaves the company, leading to the remaining tokens either being re-assigned to another employee or being moved back to the Treasury wallet." Would the reassignment be done automatically in this contract, or would the tokens be sent back to the issuer, who would then re-initialize a new vesting schedule for someone else?use casesnumber (4) states "Employee gets promoted or company gets acquired, leading to an acceleration of the vesting schedule for one or more employees." Is this acceleration be done automatically in this contract, or would the tokens be sent back to the issuer, who would then send them to the employee in question?Architecture
Walletmodule, correct?IWallet.sol. I can do what I think may be best, but without a spec I am not sure how closely I can mimic what you desire.typeof Module Factory is this(example)?typetagis this (example)?The code so far is here. I'd like you to take a look and make sure nothing is out of the ordinary. A good chunk of the business logic is there, but my next step is to integrate it with your existing architecture and then test it of course.
satyamakgec commentedon Sep 26, 2018
@shanefontaine
Yes, many possible scenarios where the employee gets the more tokens as vested ex- Performance bonus.
So if Bob started a job in ABC Inc (at 4 April 2018) and gets 10000 tokens(as joining bonus) vested for 2 years with a cliff of 6 months (half yearly). so at 4 April 2019 he has 5000 tokens(2500 at 4 oct 2018 and 2500 more at 4 April 2019) now may be the same day Bob get the performance bonus of 50000 tokens vested for 1 yr with a cliff of 6 months then in the next 4 0ct 2019 he will get 27500 tokens.
It depends upon the divisibilty of the security token by default all securitytoken with in the polymath ecosystem have 18 decimals but issuer can choose whether he/she want their ST divisible or not. so you have to keep these things in mind at the time of creation of this module.
The sum is granted at once. so whatever the tokens are assigned at first call then it gets automatically divided as per the cliffing strategy issuer or delegate (Authorised person) put into the contract.
you need to add the logic to check whether the given amount is valid as per the divisibility of the ST or not then only tokens get assigned to the vesting contract.
As per the lucidchart you need to create something like that
Ex- if Jane joins the ABC Inc and get 100000 vested tokens for a period of 2 years with a cliff of 6 months then you should write the logic that will initiate a single txn and takes Janes wallet address, noOfTokens need to vest (100000), vesting period, cliff. this txn will vest 100000 tokens and vesting schedule get started. All things need to do in a single txn.
hmm Interesting IMO employee should get a right to take its unclaimed token. But yes there will be some strategy to pull out the unclaimed tokens by the issuer after a certain challenging period. (will give you more info after internal discussion).
I prefer to be deleted no need to keep the unnecessary data we already have all the logs present in the blockchain. You will delete the vesting schedule but you need to provide two options(as described in lucidchart) to issuer/delegate related to the remaining tokens management.
(1) It will work as conjunction with STO module so suppose you created some buying restriction in your STO. ex- restriction 1 - If someone buys the token amount more than 50000 then his/her tokens get vested for 2 years with a cliff of 4 months so these 50000 tokens get vested into the vested contract with the template data provided from the STO. I think now you can compare 1 and 2 clearly.
An issuer can create some templates not too many, only those that issuer can frequently use (ex- for every new joinee, for providing gratuity etc.)
Yes, Admin can push the token.
You will have some variable in contract
unAssginedTokens(you can choose a much better name) that will keep track of remaining or canceled tokens during the creation of new vesting schedule you will have some logic that will check this variable and allocate part of these token to the new vesting schedule.No, Issuer will have the edit option to change the vesting schedule using this all the tokens get live quickly and an employee can withdraw the tokens/issuer push these tokens to them.
Architecture
For nomenclature you can check our existing module names according to that you can choose one. I prefer
VestedEscrowWallet.sol, VestedEscrowWalletFactory.sol. and yes you canIWallet.solwill be the right name..Yes 5 type works
Tags will be
Vested Wallet,Escrow, any more you can think of.shanefontaine commentedon Sep 26, 2018
Thank you for the quick response. I am implementing those changes as we speak.
On issue I am trying to wrap my head around right now is a matter of architecture. I have been reading through this, as well as a number of other references on your site about how the factories and interfaces work. I believe I understand it, but am having an issue compiling my code. When I compile it, I get the following errors:
The first error is here in my Wallet Factory. I understand that a flag is raised when the contract is an abstract contract, but I do not think that this is the case here. Is there something I am missing during this initialization?
I thought that the IModule "interface defines some functionality which is common across all modules." Why would I be getting this error if I neither edited
iModulenor seemingly interacted with it?satyamakgec commentedon Sep 27, 2018
FYI more info on this
Yes, option one will be Implemented and Issuer can retrieve any remaining unvested portion.
For your error, you need to implement a
getPermissions()function in your Module. AsIModule.solhave its declaration but you are not implementing it when you are inheriting theIModule.I hope this will help. Thanks
shanefontaine commentedon Sep 27, 2018
You said option one and issuer, which are contracdictory. Which did you mean?
CPSTL commentedon Sep 27, 2018
@shanefontaine The Employee / Affiliate should be able to claim any tokens vested up until the schedule is voided. With that being said, afterwards the Issuer can retrieve any remaining unvested portion of tokens. Does that help answer your question?
shanefontaine commentedon Sep 27, 2018
@CPSTL Yes, it does, partially. What if the employee/affiliate has unclaimed, vested tokens after void of contract. I believe (and suggest) the solution is to make it in such a way that upon cancellation, the issuer receives the unvested tokens, the employee receives all vested tokens, and the account gets deleted. Does that sound reasonable?
6 remaining items
satyamakgec commentedon Oct 4, 2018
Cool no worries!. When you submit the PR then let me know so I can start the reviewing process.
shanefontaine commentedon Oct 5, 2018
PR has been submitted.
gitcoinbot commentedon Oct 8, 2018
@shanefontaine Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!
Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days
shanefontaine commentedon Oct 8, 2018
I have submitted a PR.
gitcoinbot commentedon Oct 13, 2018
@shanefontaine Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!
Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days
shanefontaine commentedon Oct 13, 2018
I have submitted a PR.
gitcoinbot commentedon Oct 17, 2018
@shanefontaine Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!
Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days
gitcoinbot commentedon Oct 20, 2018
@shanefontaine Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!
Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days
samparsky commentedon Oct 21, 2018
@shanefontaine You have to submit the PR on gitcoin via
submit taskfor the bot to stop commentinggitcoinbot commentedon Oct 22, 2018
@shanefontaine Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!
Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days
gitcoinbot commentedon Oct 23, 2018
Issue Status: 1. Open 2. Started 3. Submitted 4. Done
@shanefontaine due to inactivity, we have escalated this issue to Gitcoin's moderation team. Let us know if you believe this has been done in error!
Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days
gitcoinbot commentedon Oct 24, 2018
Issue Status: 1. Open 2. Cancelled
The funding of 5000.0 POLY (870.0 USD @ $0.17/POLY) attached to this issue has been cancelled by the bounty submitter
gitcoinbot commentedon Oct 24, 2018
Issue Status: 1. Open 2. Cancelled
The funding of 5000.0 POLY (870.0 USD @ $0.17/POLY) attached to this issue has been cancelled by the bounty submitter
satyamakgec commentedon Jan 8, 2019
closing in the favor of #422