Define state transitions of Reward module

Hello everyone,

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 <iker@lightcurve.io>
         Mehmet Egemen Albayrak <mehmet.albayrak@lightcurve.io>
Type: Standards Track
Created: <YYYY-MM-DD>
Updated: <YYYY-MM-DD>
Requires: Random Module LIP, BFT module LIP, and Token Module LIP.

Abstract

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.

Copyright

This LIP is licensed under the Creative Commons Zero 1.0 Universal.

Motivation

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.

Rationale

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.

Specification

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.

Constants

Name Type Value
TOKEN_ID_REWARD object specified as part of module configuration
TOKEN_ID_LSK_MAINCHAIN object {"chainID": 0, "localID": 0}
REWARD_REDUCTION_FACTOR_BFT uint32 4

Token for rewards

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.

Reward Brackets

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.

Lisk Mainchain Configuration

Mainchain Rewards Token

The token for rewards on the Lisk mainchain is the LSK token, with token ID equals to TOKEN_ID_LSK_MAINCHAIN.

Mainchain Reward Brackets

The reward brackets for the Lisk Mainchain are as follows:

Heights Default Reward
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.

Internal Functions

The reward module has the following internal function.

getBlockReward

This function is used to retrieve the reward of a block at a given height.

Parameters

blockHeader: A block header.

Returns

The reward for the block as a 64-bit unsigned integer.

Execution
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

Here, / represents integer division, isValidSeedReveal is the function exposed by the random module and impliesMaximalPrevotes is the function exposed by the BFT module.

Endpoints for Off-Chain Services

The reward module exposes the following functions for off-chain services.

getDefaultRewardAtHeight

This function is used to retrieve the expected default reward at a given height.

Parameters

The height of a block as a 32-bit unsigned integer.

Returns

The default reward of the block as a 64-bit unsigned integer.

Block Processing

After Block Execution

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)

where 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.

Backwards Compatibility

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.

1 Like

This LIP has been updated to remove the reward property from the block header/assets. The reward of a block is now simply calculated and assigned after block execution.

The PR with the updated specifications has been merged.