token-mint-module.md 3.8 KB
Token Mint Module
Table of Contents
Name
TokenMint
Motivation
Assume an actor is allocating tokens on behalf of others in the service of some broad goal. First, one may want to have flexibility in the automatic constraints under which the allocation occurs. For example, one may want to
limit the total quantity within a given time period.
limit the set of possible recipients.
limit the set of possible distributions across recipients.
These limits are cannot be enforced by simply crediting a discretionary account controlled by the allocator. Moreover, one may not want to finance the allocation by a large up-front minting, but rather mint tokens as they are required.
Second, there may be multiple such actors organized into some sort of network or hierarchy, where the goals of one actor support the goals of another, and as a result, one may want an actor to be able to finance the allocative budget of another.
Design
The design centers around the idea of a token mint. A token mint has the ability to mint and transfer new tokens to an account. It has a minting capacity, which indicates how much can be minted currently, and this capacity is decreased with each minting action. A minting action is only valid if it respects the current capacity. The capacity can be changed at any time, and it can also be automatically adjusted at a given block interval, by either being set to some fixed value, adjusted by some fixed value (up or down). Lastly, a mint can transfer some part of its capacity to another mint.
Usage
The module is meant to be a low-level component of a fuller reward environment, where more context-specific modules will layer contextual permissions and requirements on top of this module. This is why there are no dispatchables or events.
Dependencies
Currency: SRML currency module
Concepts
trait Trait : Curreny::Trait {
/* Identifier type for a token mint. */
type TokenMintId: INTEGER_TRAIT_CONSTRAINTS
}
enum AdjustCapacityBy {
Setting,
Adding,
Reducing
}
struct TokenMint<T: Trait> {
id: T::TokenMintId,
capacity: T::Balance,
adjustment_type: AdjustCapacityBy,
block_interval: T::BlockNumber,
// Whether there is an upcoming block where
// When this is not set, the mint is effectively paused.
// There should be invariant check that Some(next_in_block) > now
adjust_capacity_in_block_nr: Option<T::BlockNumber>,
created: T::BlockNumber,
/// Stats
total_minted: T::Balance,
}
State
mints: T::TokenMintId => TokenMint<T>nextTokenMintId: T::TokenMintId
Events
None
Dispatchables
None
Non-dispatchable Methods
add_mint
Adds a new mint with a given settings to mints, and returns new id.
remove_mint
Removes a mint with given id from mints
transfer_tokens
Mints the given amount of tokens out of given mint and credits given account, provided it is within the current capacity, and reduces capacity correspondingly,
set_capacity
Sets capacity of given mint to new given value.
transfer_capacity
Given two mints, deducts from the capacity of one and credits capacity of the other, provided the amount respects the current capacity of the former.
on_finalize
Updates capacity of all mints where the adjust_capacity_in_block_nr value match the current block number. For such mints, the value is updated by adding block_interval.