`vesting`

Abstract

This document specifies the internal x/vesting module of the Evmos Hub.

The x/vesting module introduces the ClawbackVestingAccount, a new vesting account type that implements the Cosmos SDK VestingAccount interface. This account is used to allocate tokens that are subject to vesting, lockup, and clawback.

The ClawbackVestingAccount allows any two parties to agree on a future rewarding schedule, where tokens are granted permissions over time. The parties can use this account to enforce legal contracts or commit to mutual long-term interests.

In this commitment, vesting is the mechanism for gradually earning permission to transfer and delegate allocated tokens. Additionally, the lockup provides a mechanism to prevent the right to transfer allocated tokens and perform Ethereum transactions from the account. Both vesting and lockup are defined in schedules at account creation. At any time, the funder of a ClawbackVestingAccount can perform a clawback to retrieve unvested tokens. The circumstances under which a clawback should be performed can be agreed upon in a contract (e.g. smart contract).

For Evmos, the ClawbackVestingAccount is used to allocate tokens to core team members and advisors to incentivize long-term participation in the project.

Concepts
State
State Transitions
Transactions
AnteHandlers
Events
Clients

References

SDK vesting specification: https://docs.cosmos.network/main/modules/auth/vesting
SDK vesting implementation: https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/vesting
Agoric’s Vesting Clawback Account: https://github.com/Agoric/agoric-sdk/issues/4085
Agoric’s vestcalc tool: https://github.com/agoric-labs/cosmos-sdk/tree/Agoric/x/auth/vesting/cmd/vestcalc

Concepts

Vesting

Vesting describes the process of converting unvested into vested tokens without transferring the ownership of those tokens. In an unvested state, tokens cannot be transferred to other accounts, delegated to validators, or used for governance. A vesting schedule describes the amount and time at which tokens are vested. The duration until which the first tokens are vested is called the cliff.

Lockup

The lockup describes the schedule by which tokens are converted from a locked to an unlocked state. As long as all tokens are locked, the account cannot perform any transaction that spend EVMOS. However, the account can perform transactions that don't spend EVMOS tokens. Additionally, locked tokens cannot be transferred to other accounts. In the case in which tokens are both locked and vested at the same time, it is possible to delegate them to validators, but not transfer them to other accounts.

The following table summarizes the actions that are allowed for tokens that are subject to the combination of vesting and lockup:

Token Status	Transfer	Delegate	Vote	Eth Txs that spend EVMOS**	Eth Txs that don't spend EVMOS (amount = 0)**
`locked` & `unvested`	❌	❌	❌	❌	✅
`locked` & `vested`	❌	✅	✅	❌	✅
`unlocked` & `unvested`	❌	❌	❌	❌	✅
`unlocked` & `vested`*	✅	✅	✅	✅	✅

*Staking rewards are unlocked and vested

**EVM transactions only fail if they involve sending locked or unvested EVMOS tokens, e.g. send EVMOS to EOA or Smart Contract (fails if amount > 0 ).

Schedules

Vesting and lockup schedules specify the amount and time at which tokens are vested or unlocked. They are defined as periods where each period has its own length and amount. A typical vesting schedule for instance would be defined starting with a one-year period to represent the vesting cliff, followed by several monthly vesting periods until the total allocated vesting amount is vested.

Vesting or lockup schedules can be easily created with Agoric’s vestcalc tool. E.g. to calculate a four-year vesting schedule with a one year cliff, starting in January 2022, you can run vestcalc with:

vestcalc --write --start=2022-01-01 --coins=200000000000000000000000aevmos --months=48 --cliffs=2023-01-01

Clawback

In case a ClawbackVestingAccount's underlying commitment or contract is breached, the clawback provides a mechanism to return unvested funds. The account authorized to perform the clawback is defined during ClawbackVestingAccount account creation. It can be:

The governance module if allowed
The address specified as the FunderAddress

It should be noted that the information if an account has governance clawback enabled or not is not stored with the account itself but it is stored directly in the vesting module.

When a clawback is initiated, or by the funder or the governance, unvested tokens are send to the destination address specified in the clawback message. If no destination address is specified, the default is to return tokens to the funder.

State

State Objects

The x/vesting module does not keep objects in its own store. Instead, it uses the SDK auth module to store account objects in state using the Account Interface. Accounts are exposed externally as an interface and stored internally as a clawback vesting account.

ClawbackVestingAccount

An instance that implements the Vesting Account interface. It provides an account that can hold contributions subject to lockup, or vesting which is subject to clawback of unvested tokens, or a combination (tokens vest, but are still locked).

type ClawbackVestingAccount struct {
    // base_vesting_account implements the VestingAccount interface. It contains
    // all the necessary fields needed for any vesting account implementation
    *types.BaseVestingAccount `protobuf:"bytes,1,opt,name=base_vesting_account,json=baseVestingAccount,proto3,embedded=base_vesting_account" json:"base_vesting_account,omitempty"`
    // funder_address specifies the account which can perform clawback
    FunderAddress string `protobuf:"bytes,2,opt,name=funder_address,json=funderAddress,proto3" json:"funder_address,omitempty"`
    // start_time defines the time at which the vesting period begins
    StartTime time.Time `protobuf:"bytes,3,opt,name=start_time,json=startTime,proto3,stdtime" json:"start_time"`
    // lockup_periods defines the unlocking schedule relative to the start_time
    LockupPeriods []types.Period `protobuf:"bytes,4,rep,name=lockup_periods,json=lockupPeriods,proto3" json:"lockup_periods"`
    // vesting_periods defines the vesting schedule relative to the start_time
    VestingPeriods []types.Period `protobuf:"bytes,5,rep,name=vesting_periods,json=vestingPeriods,proto3" json:"vesting_periods"`
}

BaseVestingAccount

Implements the VestingAccount interface. It contains all the necessary fields needed for any vesting account implementation.

FunderAddress

Specifies the account which provides the original tokens and can perform clawback.

StartTime

Defines the time at which the vesting and lockup schedules begin.

LockupPeriods

Defines the unlocking schedule relative to the start time.

VestingPeriods

Defines the vesting schedule relative to the start time.

Genesis State

The x/vesting module allows the definition of ClawbackVestingAccounts at genesis. In this case, the account balance must be logged in the SDK bank module balances or automatically adjusted through the add-genesis-account CLI command.

State Transitions

The x/vesting module allows for state transitions that create and update a clawback vesting account with CreateClawbackVestingAccount or perform a clawback of unvested funds with Clawback.

Create Clawback Vesting Account

An externally owned account can be converted to a clawback vesting account by the owner. Upon creation, the owner assigns a funder, who is able to fund the account with vesting and/or lockup schedules. The account has also the possibility to specify if the vested tokens can be clawbacked from the governance.

Owner submits a MsgCreateClawbackVestingAccount through one of the clients.
Check if
1. the vesting account address is not blocked.
2. the account at the vesting account address is not already a vesting account.
Create a clawback vesting account at the target address with empty vesting and lockup schedules.

Fund Clawback Vesting Account

The funder of a clawback vesting account can fund it with vesting and/or lockup schedules. If a vesting account already has funds, the schedules are merged together.

Funder submits a MsgFundVestingAccount through one of the clients.
Check if
1. the vesting address is not a blocked address.
2. the vesting address is a clawback vesting account.
3. there is at least one vesting or lockup schedule provided. If one of them is absent, default to instant vesting or unlock schedule.
lockup and vesting total amounts are equal.
Update the clawback vesting account and send coins from the funder to the vesting account, merging any existing schedules with the new funding.

Clawback

The funding address is the only address that can perform the clawback.

Funder submits a MsgClawback through one of the clients.
Check if
1. a destination address is given and default to funder address if not
2. the destination address is not blocked
3. the account exists and is a clawback vesting account
4. account funder is same as in msg
Transfer unvested tokens from the clawback vesting account to the destination address, update the lockup schedule and remove future vesting events.

Update Clawback Vesting Account Funder

The funding address of an existing clawback vesting account can be updated only by the current funder.

Funder submits a MsgUpdateVestingFunder through one of the clients.
Check if
1. the new funder address is not blocked
2. the vesting account exists and is a clawback vesting account
3. account funder is same as in msg
Update the vesting account funder with the new funder address.

Convert Vesting Account

Once all tokens are vested, the vesting account can be converted back to an EthAccount.

Owner of vesting account submits a MsgConvertVestingAccount through one of the clients.
Check if
1. the vesting account exists and is a clawback vesting account
2. the vesting account's vesting and locked schedules have concluded
Convert the vesting account to an EthAccount

Transactions

This section defines the concrete sdk.Msg types, that result in the state transitions defined on the previous section.