Today I would like to propose a LIP for the roadmap objective “Define state transitions of Reward module”. This LIP specifies the reward module.
Looking forward to your feedback!
Here is the LIP draft:
LIP: <LIP number> Title: Define state transitions of Reward module Authors: Iker Alustiza <firstname.lastname@example.org> Mehmet Egemen Albayrak <email@example.com> Type: Standards Track Created: <YYYY-MM-DD> Updated: <YYYY-MM-DD> Requires: Random Module LIP, BFT module LIP, and Token Module LIP.
The reward module provides the base reward system for a blockchain developed with the Lisk SDK. In this LIP, we specify the protocol logic that this module injects during the block lifecycle as well as the functions that can be called from off-chain services.
This LIP is licensed under the Creative Commons Zero 1.0 Universal.
The goal of this LIP is to modularize the rewards assignment logic when a new block is generated. For this purpose, we specify the reward module, which will make it easier to customize this logic and replace it if necessary.
The reward module induces specific logic after the application of a block:
- After applying the block, a certain quantity of the native token of the blockchain is minted and assigned to the block generator. The exact amount assigned to the block generator, i.e., the reward, is calculated depending of the rules of the random module and the BFT module.
In this section, we specify the protocol logic in the lifecycle of a block injected by the reward module as well as the functions that can be called from off-chain services. This module does not contain commands, and has an empty state. It depends on the token, BFT, and random modules.
||object||specified as part of module configuration|
The reward module triggers the minting of rewards in the fungible token identified by the value of
TOKEN_ID_REWARD, which denotes a token ID. The value of
TOKEN_ID_REWARD is set according to the initial configuration of the reward module.
As part of the reward module configuration, the module has to define certain reward brackets, i.e., the values of the default block reward depending on the height of the block. For this LIP, we assume the reward brackets are given by the function
getDefaultRewardAtHeight(height), which returns a 64-bit unsigned integer value, the default block reward, given the block height
height as input.
The token for rewards on the Lisk mainchain is the LSK token, with token ID equals to
The reward brackets for the Lisk Mainchain are as follows:
|From 1,451,520 to 4,451,519||5 × 108|
|From 4,451,520 to 7,451,519||4 × 108|
|From 7,451,520 to 10,451,519||3 × 108|
|From 10,451,520 to 13,451,519||2 × 108|
|From 13,451,520 onwards||1 × 108|
This corresponds to default rewards of 5 LSK, 4 LSK, 3 LSK, 2 LSK, and 1 LSK respectively.
The reward module has the following internal function.
This function is used to retrieve the reward of a block at a given height.
blockHeader: A block header.
The reward for the block as a 64-bit unsigned integer.
getBlockReward(blockHeader): if isValidSeedReveal(blockHeader.generatorAddress, blockHeader.seedReveal) == false: return 0 defaultReward = getDefaultRewardAtHeight(blockHeader.height) if impliesMaximalPrevotes(blockHeader) == false: return defaultReward / REWARD_REDUCTION_FACTOR_BFT return defaultReward
The reward module exposes the following functions for off-chain services.
This function is used to retrieve the expected default reward at a given height.
The height of a block as a 32-bit unsigned integer.
The default reward of the block as a 64-bit unsigned integer.
After a block
b is executed, the
mint function exposed by the token module to assign the reward to the block generator as:
blockReward = getBlockReward(b.header) mint(b.header.generatorAddress, TOKEN_ID_REWARD, blockReward)
TOKEN_ID_REWARD is the token ID of the token used for the reward system of the blockchain. In the case of the Lisk mainchain,
TOKEN_ID_REWARD = TOKEN_ID_LSK_MAINCHAIN.
This LIP defines the interface for the reward module but does not introduce any change to the protocol, hence it is a backward compatible change.