cfevesting

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 24, 2023 License: Apache-2.0 Imports: 24 Imported by: 0

README

Chain4Energy vesting module - cfevesting

Abstract

Chain4Energy vesting module allows to create and manage vesting pools. One can create a vesting pool in order to lock a certain amount of tokens for a period of time. During this locking period the locked tokens can only be used for continuous vesting accounts creation. The vesting account parameters are calculated from the vesting pool configuration.

Contents

  1. Concept
  2. Params
  3. State
  4. Messages
  5. Events
  6. Queries
  7. Invariants
  8. Genesis validations

Concepts

The purpose of cfevesting module is to provide the functionality of locking tokens in a pool for specified amount of time with the ability of sending those tokens to continuous vesting accounts. The tokens will be still locked on the vesting accounts, and it will not be possible to sent them further until the locking period ends. This allows to create vesting target groups (e.g. validators vesting pool, investors vesting pools). The cfevesting module keeps track of all the vesting pools and vesting accounts and allows to calculate the total amount of tokens in vesting.

Vesting Pool

Vesting pool locks a certain amount of tokens for configured period of time. Each vesting pool has its owner (creator account). A single owner can have multiple vesting pools. Each vesting pool is identified by its unique name (unique among all the pools belonging to a single owner).

Vesting pools have the following parameters:

  • name - unique name (among owner's pools)
  • vesting type - vesting type used by vesting pool (see Vesting Type)
  • lock start - time of pool creation
  • lock end - unlocking time (end of lock period)
  • initially_locked - amount of tokens locked initially in the pool
  • withdrawn - amount of tokens that were already withdrawn from the pool (currently all available (available = initially_locked - sent) tokens can be withdrawn by the owner only after lock end time)
  • sent - amount of tokens that were already sent to vesting accounts from the vesting pool
Vesting Type

Vesting type defines the parameters of continuous vesting accounts that will be created from a given vesting pool. Vesting type has the following parameters:

  • name - unique name
  • lockup period - period of time when all the tokens in the pool are locked
  • vesting period - period of time when tokens are linearly vested
  • free - the percentage of tokens that will be released at the beginning after sending to a continuous vesting account

New vesting account parameters will be set accordingly:

  • continuous vesting account start time = last block time + vesting type lockup period
  • continuous vesting account end time = last block time + vesting type lockup period + vesting type vesting period

The vesting types are predefined on genesis.

Parameters

The Chain4Energy vesting module contains the following configurations parameters:

Key Type Description
denom string Denom of vesting token

State

Vesting pools state

Chain4Energy vesting module state contains vesting pools lists per owner.

AccountVestingPool type
Key Type Description
address string Owner address
vesting_pools List of VestingPool types Vesting pools of the owner
VestingPool type
Key Type Description
name string unique name per owner
vesting_type string vesting type used by vesting pool (see Vesting Type)
lock_start time.Duration time of pool creation
lock_end time.Duration unlocking time (end of lock period)
initially_locked sdk.Int amount of tokens locked initially in the pool
withdrawn sdk.Int amount of tokens that were already withdrawn from the pool
sent sdk.Int amount of tokens that were already sent to vesting accounts from the vesting pool
Vesting types data dictionary

Vesting types data dictionary contains list of predefined vesting types:

Key Type Description
name string unique vesting type name
lockup_period time.Duration period of time when all tokens are locked
vesting_period time.Duration period of time when tokens are are linearly vested
Vesting account list

Vesting account list contains address of all vesting accounts created with cfevesting module.

VestingAccount type
Key Type Description
id uint64 id of an entity in the vesting accounts list
address string vesting account address

Messages

Create Vesting Pool

Creates new vesting pool for the creator account.

MsgCreateVestingPool can be submitted by any token holder via a MsgCreateVestingPool transaction.

type MsgCreateVestingPool struct {
	Creator     string
	Name        string
	Amount      sdk.Int
	Duration    time.Duration
	VestingType string
}

Params:

Param Description
Creator Creator/Owner address
Name Vesting pool name
Amount Amount to lock in the vesting pool
Duration Lock duration
VestingType Vesting Type of the pool

State modifications:

  • Validate Creator has enough tokens
  • Generate new VestingPool record for creator/owner
  • Save the record in the owner account vesting pools list
  • Transfer the tokens from the Creator account to cfevesting ModuleAccount.
Send To Vesting Account

Creates a new continuous vesting account and sends tokens from vesting pool to it.

MsgSendToVestingAccount can be submitted by any Vesting pool owner via a MsgSendToVestingAccount transaction.

type MsgSendToVestingAccount struct {
	FromAddress     string
	ToAddress       string
	VestingPoolName string
	Amount          sdk.Int
	RestartVesting  bool
}

Params:

Param Description
FromAddress Vesting pool owner address
ToAddress New continuous vesting account address
VestingPoolName Vesting pool name
Amount Amount to lock in the vesting pool
RestartVesting Defines how time parameters of new vesting account should be calculatad:
- true:
   continuous vesting account start time = last block time + vesting type lockup period
   continuous vesting account end time = last block time + vesting type lockup period + vesting type vesting period
- false:
   continuous vesting account start time = vesting pool lock end
   continuous vesting account end time = vesting pool lock end

State modifications:

  • Validates if FromAddress owner's vesting pool VestingPoolName has enough tokens
  • Creates new continuous vesting account with ToAddress address and the time params calculated according to the pool vesting type
  • Sends tokens from cfevesting ModuleAccount to ToAddress
  • Updates the vesting pool state
Withdraw All Available

Withdraws all available (unlocked) tokens from the vesting pool back to the owner account

MsgWithdrawAllAvailable can be submitted by any vesting pool owner via a MsgWithdrawAllAvailable transaction.

type MsgWithdrawAllAvailable struct {
	Creator string
}
Param Description
Creator Vesting pool owner address

State modifications:

  • Sends unlocked tokens from cfevesting ModuleAccount to Creator account
  • Updates the vesting pool state
Create Vesting Account

Creates new continuous vesting account and sends token from creator account.

MsgCreateVestingAccount can be submitted by any token holder via a MsgCreateVestingAccount transaction.

type MsgCreateVestingAccount struct {
	FromAddress string
	ToAddress   string
	Amount      sdk.Coins`
	StartTime   int64
	EndTime     int64
}

Params:

Param Description
FromAddress Vesting pool owner address
ToAddress New continuous vesting account address
Amount Amount to lock in vesting account
StartTime Vesting start time - unix
EndTime Vesting end time - unix

State modifications:

  • Validates if FromAddress has enough tokens
  • Creates new continuous vesting account with address equal to ToAddress and time params according to provided data
  • Sends tokens from FromAddress account to ToAddress

Events

Chain4Energy distributor module emits the following events:

Handlers
MsgCreateVestingPool
Type Attribute Key Attribute Value
NewVestingPool creator {creator_owner_address}
NewVestingPool name {vesting_pool_name}
NewVestingPool amount {vesting_pool_amount}
NewVestingPool duration {lock_duration}
NewVestingPool vesting_type {vesting_type_name}
message action ??
message sender ??
transfer recipient {moduleAccount}
transfer sender {creator}
transfer amount {amount}

// TODO verify

MsgSendToVestingAccount
Type Attribute Key Attribute Value
WithdrawAvailable owner_address {owner_address}
WithdrawAvailable vesting_pool_name {source_vesting_pool_name}
WithdrawAvailable amount {withdrawn_amount}
NewVestingAccountFromVestingPool owner_address {owner_address}
NewVestingAccountFromVestingPool address {new_vesting_account_address}
NewVestingAccountFromVestingPool vesting_pool_name {source_vesting_pool_name}
NewVestingAccountFromVestingPool amount {amount_to_send_to_new_vesting_account}
NewVestingAccountFromVestingPool restart_vesting {restart_vesting} see Send To Vesting Account
message action ??
message sender ??
transfer recipient {moduleAccount}
transfer sender {creator}
transfer amount {amount}

// TODO verify

MsgWithdrawAllAvailable
Type Attribute Key Attribute Value
WithdrawAvailable owner_address {owner_address}
WithdrawAvailable vesting_pool_name {source_vesting_pool_name}
WithdrawAvailable amount {withdrawn_amount}
message action ??
message sender ??
transfer recipient {moduleAccount}
transfer sender {creator}
transfer amount {amount}

// TODO verify

MsgCreateVestingAccount
Type Attribute Key Attribute Value
NewVestingAccount address {new_vesting_account_address}
message action ??
message sender ??
transfer recipient {moduleAccount}
transfer sender {creator}
transfer amount {amount}

// TODO verify - some more params

Queries

Params query

Queries the module params.

See example response:

{
  "params": {
    "denom": "uc4e"
  }
}
Summary query

Queries the vesting summary data.

See example response:

{
  "vesting_all_amount": "32500000000000",
  "vesting_in_pools_amount": "32500000000000",
  "vesting_in_accounts_amount": "0",
  "delegated_vesting_amount": "0"
}
Vesting pool query

Queries the vesting pools owned by account with given address.

See example response:

{
  "vesting_pools": [
    {
      "name": "Advisors pool",
      "vesting_type": "Advisors pool",
      "lock_start": "2022-03-30T00:00:00Z",
      "lock_end": "2025-03-30T00:00:00Z",
      "withdrawable": "0",
      "initially_locked": {
        "denom": "uc4e",
        "amount": "15000000000000"
      },
      "currently_locked": "15000000000000",
      "sent_amount": "0"
    },
    {
      "name": "Validators pool",
      "vesting_type": "Validators pool",
      "lock_start": "2022-03-30T00:00:00Z",
      "lock_end": "2024-03-30T00:00:00Z",
      "withdrawable": "0",
      "initially_locked": {
        "denom": "uc4e",
        "amount": "17500000000000"
      },
      "currently_locked": "17500000000000",
      "sent_amount": "0"
    }
  ]
}
Vesting types query

Queries the vesting types.

See example response:

{
  "vesting_types": [
    {
      "name": "Advisors pool",
      "lockup_period": "5",
      "lockup_period_unit": "minute",
      "vesting_period": "5",
      "vesting_period_unit": "day"
    },
    {
      "name": "Validators pool",
      "lockup_period": "10",
      "lockup_period_unit": "minute",
      "vesting_period": "10",
      "vesting_period_unit": "day"
    }
  ]
}

Invariants

Non-Negative Vesting Pool Amounts Invariant

Invariant validates vesting pools state. Checks if all vesting pools amounts are non-negative

Vesting Pool Consistent Data Invariant

Invariant validates vesting pools state. Checks if all vesting pools amounts are consistent: withdrawn + sent < initially locked

Module Account Invariant

Invariant validates vesting pools state. Checks if sum of all amounts locked in vesting pools is equal to module account balance.

Genesis validations

TODO

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExportGenesis

func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState

ExportGenesis returns the capability module's exported genesis.

func InitGenesis

func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState, ak types.AccountKeeper, bk types.BankKeeper, sk types.StakingKeeper)

InitGenesis initializes the capability module's state from a provided genesis state.

func NewHandler

func NewHandler(k keeper.Keeper) sdk.Handler

NewHandler ...

func ValidateAccountsOnGenesis

func ValidateAccountsOnGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState,
	ak types.AccountKeeper, bk types.BankKeeper, sk types.StakingKeeper) error

Types

type AppModule

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the capability module.

func NewAppModule

func NewAppModule(
	cdc codec.Codec,
	keeper keeper.Keeper,
	accountKeeper types.AccountKeeper,
	bankKeeper types.BankKeeper,
	stakingKeeper types.StakingKeeper,
) AppModule

func (AppModule) BeginBlock

func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock executes all ABCI BeginBlock logic respective to the capability module.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements ConsensusVersion.

func (AppModule) EndBlock

EndBlock executes all ABCI EndBlock logic respective to the capability module. It returns no validator updates.

func (AppModule) ExportGenesis

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the capability module's exported genesis state as raw JSON bytes.

func (AppModule) GenerateGenesisState

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the module

func (AppModule) InitGenesis

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the capability module's genesis initialization It returns no validator updates.

func (AppModule) LegacyQuerierHandler

func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns the capability module's Querier.

func (AppModule) Name

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) ProposalContents

ProposalContents doesn't return any content functions for governance proposals

func (AppModule) QuerierRoute

func (AppModule) QuerierRoute() string

QuerierRoute returns the capability module's query routing key.

func (AppModule) RandomizedParams

func (am AppModule) RandomizedParams(_ *rand.Rand) []simtypes.ParamChange

RandomizedParams creates randomized param changes for the simulator

func (AppModule) RegisterInvariants

func (am AppModule) RegisterInvariants(ir sdk.InvariantRegistry)

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) RegisterStoreDecoder

func (am AppModule) RegisterStoreDecoder(_ sdk.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder

func (AppModule) Route

func (am AppModule) Route() sdk.Route

Route returns the capability module's message routing key.

func (AppModule) WeightedOperations

func (am AppModule) WeightedOperations(_ module.SimulationState) []simtypes.WeightedOperation

WeightedOperations returns the all the gov module operations with their respective weights.

type AppModuleBasic

type AppModuleBasic struct {
	// contains filtered or unexported fields
}

AppModuleBasic implements the AppModuleBasic interface for the capability module.

func NewAppModuleBasic

func NewAppModuleBasic(cdc codec.BinaryCodec) AppModuleBasic

func (AppModuleBasic) DefaultGenesis

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns the capability module's default genesis state.

func (AppModuleBasic) GetQueryCmd

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the capability module's root query command.

func (AppModuleBasic) GetTxCmd

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the capability module's root tx command.

func (AppModuleBasic) Name

func (AppModuleBasic) Name() string

Name returns the capability module's name.

func (AppModuleBasic) RegisterCodec

func (AppModuleBasic) RegisterCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterGRPCGatewayRoutes

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces

func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterRESTRoutes

func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the capability module.

Directories

Path Synopsis
client
cli
migrations
Package types is a reverse proxy.
Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL