# TokenLock

TokenLock is an cosmos sdk style module, that is used to manage Locking and unlocking XYZ tokens on any account. This module has the ability to lock the account from transfering XYZ token unless unlocked.

## 1. Concept
- This module defines messages and interfaces which will initialize the minter and grants him authority to lock/unlock tokens on any account.
- This module provides an interface, to lock/unlock tokens and query the number of locked tokens. Before transfer of any funds a validation check can be done,to know whether the tokens are freezed.
- Minter can delegate his authority to any other account.
- Minter can be initialized during the genesis state.
- This module can be extended to support automated time based locking/unlocking mechanism.

## 2. State
### Minter
- Minter authority is defined by account address, if the address is 0x00(default), it means network level locking/unlocking mechanism is enabled.
`Minter: AccountAddress`
### LockedTokens
- LockedTokens structure is defined by number of tokens locked and interval.
- These structures can be referenced by a standard prefix,for example: lock-value-address, such prefixing can be very helpful to quickly retrieve the locked funds associated with a specific account address.
`LockedTokens {lock-value-address: amount, interval}`

### LockedTokensList

- Usefull structure to list all the addresses with locked funds.
`list :[]byte(address)`

## 3. Messages
### MsgLock
- This message struct implements the standard cosmos sdk message interface. Input parameters include account address, number of tokens to be locked and interval.

`Msglock: {accaddress,amount,interval}`
`
### MsgUnLock
- This message struct implements the standard cosmos sdk message interface. Input parameters include account address, number of tokens to be unlocked.

``MsgUnLock: {accaddress,amount}``

## 4. Keepers

### BaseTransferKeeper
- Parent Keeper of both bank and tokenLock keeper which implements all the logic related to transfer of funds, this will call bank keeper transfer logic after checking the number of available funds.
`Keeper { storeKey sdk.StoreKey cdc *codec.Codec TokenLockKeeper, bankKeeper types.bankkeeper,tokenLockKeeper types.tokenLockKeeper }`
### TokenLockKeeper
- Keeper has access to store keys, codec and other module keepers. This keeper is registered with app module.
- `Keeper { storeKey sdk.StoreKey cdc *codec.Codec TokenLockKeeper types.TokenLockKeeper }`
- Inside the keeper we define how tokens have to be locked and unlocked, state logic is defined within the keeper.

Note: BankKeeper default transfer logic has to be overridden.

## 5. Events

### LockSuccessfull

- Emitted once MsgLock call is successfull

{
  "type": "LockSuccessfull",
  "attributes": [
    {
      "key": "Address",
      "value": "{{sdk.AccAddress of the module}}",
      "index": true
    },
    {
      "key": "amount",
      "value": "{{sdk.Coins being Locked}}",
      "index": true
    }
  ]
}

- It will be usefull to notify all the watching actors in the network.

### UnLockSuccessfull
- Emitted once MsgUnLock call is successfull

{
  "type": "UnLockSuccessfull",
  "attributes": [
    {
      "key": "Address",
      "value": "{{sdk.AccAddress of the module}}",
      "index": true
    },
    {
      "key": "amount",
      "value": "{{sdk.Coins being UnLocked}}",
      "index": true
    }
  ]
}

- It will be usefull to notify all the watching actors in the network.

## 6. Client

### Balances
- A user can query the latest balance

Example output:

balances:
- amount: "1000"
  denom: XYZ
pagination:
  next_key: null
  total: "0"

### LockedFunds
- A user can query number of locked funds.

LockedTokens:
- address: cosmos14e3pdrhtdv6nccgd6sg8a6wsqhaqfnugts7
- amount: "100"
  denom: XYZ
- interval: 10  
pagination:
  next_key: null
  total: "0"

### AccountsLockedList

- A user can retrieve list of accounts which have locked funds

LockedAccountsList:
- 0 : cosmos14e3pdrhtdv6nccgd6sg8a6wsqhaqfnugts7
- 1: cosmos1d7gml5j695hjx5z7cy2s045tt5me592u06kh
   
pagination:
  next_key: null
  total: "0"