cosmos-sdk/x/accounts/defaults/lockup

Lockup Accounts

• Lockup Account Types
  • BaseLockup
  • ContinuousLockup
  • DelayedLockup
  • PeriodicLockup
  • PermanentLocked
• Genesis Initialization
• Examples
  • Simple
  • Slashing
  • Periodic Lockup

The x/accounts/defaults/lockup module provides the implementation for lockup accounts within the x/accounts module.

Lockup Account Types

BaseLockup

The base lockup account is used by all default lockup accounts. It contains the basic information for a lockup account. The Base lockup account keeps knowledge of the staking delegations from the account.

type BaseLockup struct {
	// Owner is the address of the account owner.
	Owner            collections.Item[[]byte]
	OriginalLocking  collections.Map[string, math.Int]
	DelegatedFree    collections.Map[string, math.Int]
	DelegatedLocking collections.Map[string, math.Int]
	WithdrawedCoins  collections.Map[string, math.Int]
	addressCodec     address.Codec
	headerService    header.Service
	// lockup end time.
	EndTime collections.Item[time.Time]
}

ContinuousLockup

The continuous lockup account has a future start time and begins unlocking continuously until the specified end date.

To determine the amount of coins that are vested for a given block time T, the following is performed:

1. Compute X := T - StartTime
2. Compute Y := EndTime - StartTime
3. Compute V' := OV * (X / Y)
4. Compute V := OV - V'

Thus, the total amount of vested coins is V' and the remaining amount, V, is lockup.

type ContinuousLockingAccount struct {
	*BaseLockup
	StartTime collections.Item[time.Time]
}

DelayedLockup

The delayed lockup account unlocks all tokens at a specific time. The account can receive coins and send coins. The account can be used to lock coins for a long period of time.

type DelayedLockingAccount struct {
	*BaseLockup
}

PeriodicLockup

The periodic lockup account locks tokens for a series of periods. The account can receive coins and send coins. After all the periods, all the coins are unlocked and the account can send coins.

Periodic lockup accounts require calculating the coins released during each period for a given block time T. Note that multiple periods could have passed when calling GetVestedCoins, so we must iterate over each period until the end of that period is after T.

1. Set CT := StartTime
2. Set V' := 0

For each Period P:

1. Compute X := T - CT
2. IF X >= P.Length
   1. Compute V' += P.Amount
   2. Compute CT += P.Length
   3. ELSE break
3. Compute V := OV - V'

type PeriodicLockingAccount struct {
	*BaseLockup
	StartTime      collections.Item[time.Time]
	LockingPeriods collections.Vec[lockuptypes.Period]
}

PermanentLocked

The permanent lockup account permanently locks the coins in the account. The account can only receive coins and cannot send coins. The account can be used to lock coins for a long period of time.

type PermanentLockingAccount struct {
	*BaseLockup
}

Genesis Initialization

Examples

Simple

Given a continuous lockup account with 10 vested coins.

OV = 10
DF = 0
DV = 0
BC = 10
V = 10
V' = 0

1. Immediately receives 1 coin

   BC = 11
   

2. Time passes, 2 coins vest

   V = 8
   V' = 2
   

3. Delegates 4 coins to validator A

   DV = 4
   BC = 7
   

4. Sends 3 coins

   BC = 4
   

5. More time passes, 2 more coins vest

   V = 6
   V' = 4
   

6. Sends 2 coins. At this point, the account cannot send anymore until further coins vest or it receives additional coins. It can still, however, delegate.

   BC = 2
   

Slashing

Same initial starting conditions as the simple example.

1. Time passes, 5 coins vest

   V = 5
   V' = 5
   

2. Delegate 5 coins to validator A

   DV = 5
   BC = 5
   

3. Delegate 5 coins to validator B

   DF = 5
   BC = 0
   

4. Validator A gets slashed by 50%, making the delegation to A now worth 2.5 coins

5. Undelegate from validator A (2.5 coins)

   DF = 5 - 2.5 = 2.5
   BC = 0 + 2.5 = 2.5
   

6. Undelegate from validator B (5 coins). The account at this point can only send 2.5 coins unless it receives more coins or until more coins vest. It can still, however, delegate.

   DV = 5 - 2.5 = 2.5
   DF = 2.5 - 2.5 = 0
   BC = 2.5 + 5 = 7.5
   

   Notice how we have an excess amount of DV.

Periodic Lockup

A lockup account is created where 100 tokens will be released over 1 year, with 1/4 of tokens vesting each quarter. The lockup schedule would be as follows:

Periods:
- amount: 25stake, length: 7884000
- amount: 25stake, length: 7884000
- amount: 25stake, length: 7884000
- amount: 25stake, length: 7884000

OV = 100
DF = 0
DV = 0
BC = 100
V = 100
V' = 0

1. Immediately receives 1 coin

   BC = 101
   

2. Lockup period 1 passes, 25 coins vest

   V = 75
   V' = 25
   

3. During lockup period 2, 5 coins are transferred and 5 coins are delegated

   DV = 5
   BC = 91
   

4. Lockup period 2 passes, 25 coins vest

   V = 50
   V' = 50