Research vesting options.

[dwedul-figure]

Summary

We will soon have a need for folks to start vesting in hash. As such, we need to research what's available in order to make a plan on how that will be done.

This issue will house notes and opinions on how best to handle hash vesting and can be closed once a course of action has been decided.

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[dwedul-figure]

Cosmos-SDK supports vesting accounts in the auth module. The documentation can be found here: https://docs.cosmos.network/master/modules/auth/05_vesting.html

Overview

The major benefit of using a vesting account is that unvested coin can be delegated, and the returns are free to use.

Technically, a vesting account contains all the coin that will eventually be vested. There are no events, TXs, or data manipulation that marks when coin becomes vested. Instead, the amounts are calculated ad hoc as needed. When looking at the balance of a vesting account, it returns all of its coin (even the unvested portions). There is a gRPC endpoint to get the sendable balance, but no CLI for it. There's also no easy way to look up things specific to the vesting, e.g. how much has vested and how much is yet to vest.

Another drawback of vesting accounts is that there's no way for the originator to terminate vesting early and have the unvested funds returned. For example, if an employee is hired, and a vesting account is created for them, then they quit after a week, there's no way to return the unvested coin to the originator.

Vesting account types

There are 4 types of vesting accounts: continuous, delayed, periodic and permanent locked. Only the continuous and delayed ones account types can be created using a TX. Both periodic and permanent locked can only be created through genesis or as part of an upgrade.

• A continuous vesting account linearly vests coin from instantiation until the end time.
• A delayed vesting account vests all coin at the provided time.
• A periodic vesting account allows definition of specific amounts and times that those amounts should vest.
• A permanent locked vesting account permanently locks coins away. The account owner won't be able to send those coins, and they will never vest, but they can still be used for delegation and voting power.

A continuous vesting schedule is the type that probably makes the most sense for us. The primary benefit is that one can be created using a TX. It's also much closer to what usually occurs on a vesting schedule. The only real drawback is with how to the handle bookkeeping outside of the blockchain world. Basically, what then counts as a taxable event? Since I'm neither an accountant or a tax preparer, I'm going to just leave that question hanging.

A delayed vesting account is a cliff (without any follow-up vesting events). It probably doesn't suit our needs, but it is one of the two types that can be created using a TX. It might be tempting to use one for an initial cliff, but the usual purposes of a cliff is to encourage employees to stay for a period. And since there's no way to claw the coin back, that purpose is defeated.

The usual startup vesting schedule looks most like a periodic vesting account where the first entry is a year out (the cliff) and then there are several smaller amount entries (i.e. one for every two week period). However, we can only create these as part of an upgrade. Additionally, each period is defined as seconds after the previous period. So calculating all those timespans can be error prone if we still want them to coincide with paychecks. A standard 4 year schedule with a 1 year cliff and twice a month vestments after that would require 73 periods to be defined and stored.

A permanent locked vesting account is also probably not what we want. The only actual compensation it would provide would be through delegation (which currently isn't very much at all). Additionally, there's no way to every get that coin back for other use. Locking away utility token doesn't seem like a smart thing to do.

Other options

It might be possible to create our own vesting accounts (which would probably require our own custom vesting module). This would not be an easy task. And because it involves non-blockchain-related accounting, would require extra scrutiny. One major hurdle that we would need to address is how to handle a clawback, which does not have a trivial answer.

Another option would be to just use regularly scheduled send TXs. This has the benefit of being stoppable (e.g. if an employee leaves). It is also much closer to what happens when the thing vesting is stock, so the real-world accounting is already solved. The downside is that the receiver misses out on a lot of delegation rewards that they'd be able to get if a vesting account were used.

There's also an in-between option where vesting accounts are used, but multiple are created at different times during an employee's tenure. E.g. when they're hired, a delayed vesting account is created for them that vests after 1 year. Then at each anniversary, if they're still an employee, a continuous vesting account is created to cover that year. That would reduce the amount of delegation rewards the employee might receive, but would also protect the company if they left.

[dwedul-figure]

Another thing to consider is that an account cannot be enhanced to become a vesting account. An account can only be created as a vesting account, and the vesting schedule cannot then be altered (except maybe through an upgrade). And since the employee only sees the benefit of using a vesting account if it's their own account, the employee would need to create the account (e.g. provenanced keys add danny-vesting-1) and communicate the account address to whoever will be setting up the vesting account. Basically, every time a vesting account is to be created, there would need to be coordination between the employee and whoever's actually creating the account. The alternative would be to have one person create everything and then communicate the mnemonic to the employee, but that opens up a huge can of security worms.

Basically, the more accounts that are involved, the more burdensome the process will be.

[dwedul-figure]

I hate to say it, but the more I think about it, the less I like the vesting accounts. Using them would mean extra delegation rewards for me, but they just don't seem like a viable solution for us.

[dwedul-figure]

The Algoric blockchain made some additions to the vesting stuff in their own Cosmos-SDK fork that we might want to consider: agoric-labs/cosmos-sdk#155

Also, there is a Cosmos-SDK issue for adding the same functionality into the main repo: Cosmos-SDK.

So maybe we should plan on doing something similar to our own cosmos-sdk fork so that we can use the stuff without having to wait on upstream.

[dwedul-figure]

Issue #916 created to address the problems identified in this research issue.

[dwedul-figure]

Process for creating a vesting account (at least as of v1.10.0, Jun 11, 2022):

1. Recipient generates the keys to a new account. Using my-vesting-account-1 here for the name of my key in my keychain, can be whatever the recipient wants.

   > provenanced keys add my-vesting-account-1 | tee my-vesting-account-1-key.json
   {"name":"employee-9","type":"local","address":"tp1kexmry5n344aj3cd3fukylh4w3ccwecg7tsdvz","pubkey":"{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"AqcXF160XpJ2z6yOgbgvDhTws1wXNhH11LxcnbAIXhhy\"}","mnemonic":"lady click album excuse banana penalty book arch thought raise antenna screen allow prosper involve drive bottom robust normal beyond man lord myth rain"}
   

2. Recipient gets their address and sends it to the granter:

   > provenanced keys show my-vesting-account-1 | jq -r '.address'
   tp1kexmry5n344aj3cd3fukylh4w3ccwecg7tsdvz
   

   Then send that via email or text or whatever to the granter.
3. Granter creates vesting account from their own funds:

   > prov tx vesting create-vesting-account tp1kexmry5n344aj3cd3fukylh4w3ccwecg7tsdvz \
   1000000000nhash \
   "$(( $( date +%s ) + 31536000 ))" \
   --delayed \
   --from for-vesting \
   --gas auto --gas-prices 1905nhash --gas-adjustment 1.3 --yes
   

   In the above, tp1kexmry5n344aj3cd3fukylh4w3ccwecg7tsdvz is the recipient address.
   The grant amount is 1000000000nhash (must be in nhash).
   The "$(( $( date +%s ) + 31536000 ))" part is the end date/time, which must be in seconds since epoch. In this example, it is "one year from now". The number of seconds in a year is 31536000 (=606024*365), and date +%s is the seconds from the epoch until now.
   The --delayed flag creates the vesting account as a cliff. With it, all coin is vested at the end date. Without it, vesting is linearly continuous starting at account creation, with the last little bit finally vesting on the end date.
   The for-vesting string is the granter's keychain name of the account that the coins will come from.

[SpicyLemon]

Recommended actions:

1. Make same/similar changes as feat: implement true vesting accounts with clawback agoric-labs/cosmos-sdk#155: Vesting accounts: Add clawback #944
2. Allow vesting coin/schedules to be added to an existing account: Vesting accounts: Add to existing account #945