diff --git a/docs/proto/mint.md b/docs/proto/mint.md index bc9616f0f..c28ba227f 100644 --- a/docs/proto/mint.md +++ b/docs/proto/mint.md @@ -4,43 +4,21 @@ -## Purpose +## Function -The Minting Module is a fundamental component within the blockchain ecosystem, responsible for managing the dynamic -issuance of tokens to validators, thereby ensuring the stability and sustainability of the network. -This module operates on a continuous basis, recalculating parameters with each new block to maintain an optimal -token supply. +The Minting Module plays a crucial role in the blockchain ecosystem, tasked with regulating the issuance of tokens to +validators. This ensures the network's ongoing stability and viability. The module operates consistently, adjusting +key parameters with each block to maintain a balanced token supply. -## 🧮 Calculation +## Calculation of Inflation -The formula for calculating the yearly staking reward target (srty) is as follows: +The method for determining the inflation rate is outlined in the +[OKP4 Whitepaper - Token Model](https://docs.okp4.network/whitepaper/token-model). -``` -srty = a • i • (c - b / bt) -``` +## Per-Block Token Generation -- `srty`: Represents the yearly staking reward target. -- `a`: Denotes the total token supply within the blockchain. -- `i`: Refers to the inflation coefficient, a configurable parameter set at 0.073 by default. -- `c`: Signifies the bonding ratio adjustment coefficient. -- `b`: A dynamic variable ranging from 0 to 1, symbolizing the current bonding ratio at the current block. -- `bt`: Represents the target bonding ratio, conventionally set to 0.66. - -### Yearly Inflation Rate - -Upon the determination of srty, the Minting Module proceeds to convert it into a yearly inflation rate -expressed as a percentage (Iy): - -``` -Iy = (srty • 100) / a = (a • i • (c - b / bt) • 100) / a = i • (c - b / bt) • 100 -``` - -- `Iy` (in percentage): Represents the yearly inflation rate. - -### Block-Level Token Minting - -With the yearly inflation rate in hand, the Minting Module can calculate the number of tokens to be minted for -each individual block by knowing the number of block in one years. +Given the annual inflation rate, the Minting Module calculates the exact amount of tokens to be generated for each +block, based on the total number of blocks in a year. ## Table of Contents @@ -78,33 +56,24 @@ each individual block by knowing the number of block in one years. ### Minter -Minter represents the minting state within the blockchain, tasked with the continuous calculation and distribution -of tokens to validators. - -This calculation occurs with each block, where the minting module dynamically recalculates the annual `inflation` rate. -Using the resulting inflation rate, it deduces the quantity of tokens to be provisioned for the upcoming year. - -Furthermore, based on the current block's position within the year, it computes the exact number of tokens to be -minted for that specific block. +Minter holds the state of minting within the blockchain. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| `inflation` | [string](#string) | | Represents the current annual inflation rate. | -| `annual_provisions` | [string](#string) | | Represents the current annual expected provisions. | +| `inflation` | [string](#string) | | Current annual inflation rate. | +| `annual_provisions` | [string](#string) | | Current annual anticipated provisions. | ### Params -Params holds parameters for the mint module. +Params defines the parameters for the mint module. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| `mint_denom` | [string](#string) | | Type of coin to mint | -| `inflation_coef` | [string](#string) | | Annual inflation coefficient | -| `bonding_adjustment` | [string](#string) | | Bonding adjustment | -| `target_bonding_ratio` | [string](#string) | | Represent the target bonding ratio to reach | -| `blocks_per_year` | [uint64](#uint64) | | Estimated blocks per year | +| `mint_denom` | [string](#string) | | Denomination of the coin to be minted. | +| `inflation_coef` | [string](#string) | | Annual inflation coefficient, influencing the inflation rate based on the bonded ratio. Values range from 0 to 1, with higher values indicating higher inflation. | +| `blocks_per_year` | [uint64](#uint64) | | Estimated number of blocks per year. | [//]: # (end messages) diff --git a/proto/mint/docs.yaml b/proto/mint/docs.yaml index b256a1dda..bccc00382 100644 --- a/proto/mint/docs.yaml +++ b/proto/mint/docs.yaml @@ -1,38 +1,16 @@ description: | - ## Purpose + ## Function - The Minting Module is a fundamental component within the blockchain ecosystem, responsible for managing the dynamic - issuance of tokens to validators, thereby ensuring the stability and sustainability of the network. - This module operates on a continuous basis, recalculating parameters with each new block to maintain an optimal - token supply. + The Minting Module plays a crucial role in the blockchain ecosystem, tasked with regulating the issuance of tokens to + validators. This ensures the network's ongoing stability and viability. The module operates consistently, adjusting + key parameters with each block to maintain a balanced token supply. - ## 🧮 Calculation + ## Calculation of Inflation - The formula for calculating the yearly staking reward target (srty) is as follows: + The method for determining the inflation rate is outlined in the + [OKP4 Whitepaper - Token Model](https://docs.okp4.network/whitepaper/token-model). - ``` - srty = a • i • (c - b / bt) - ``` + ## Per-Block Token Generation - - `srty`: Represents the yearly staking reward target. - - `a`: Denotes the total token supply within the blockchain. - - `i`: Refers to the inflation coefficient, a configurable parameter set at 0.073 by default. - - `c`: Signifies the bonding ratio adjustment coefficient. - - `b`: A dynamic variable ranging from 0 to 1, symbolizing the current bonding ratio at the current block. - - `bt`: Represents the target bonding ratio, conventionally set to 0.66. - - ### Yearly Inflation Rate - - Upon the determination of srty, the Minting Module proceeds to convert it into a yearly inflation rate - expressed as a percentage (Iy): - - ``` - Iy = (srty • 100) / a = (a • i • (c - b / bt) • 100) / a = i • (c - b / bt) • 100 - ``` - - - `Iy` (in percentage): Represents the yearly inflation rate. - - ### Block-Level Token Minting - - With the yearly inflation rate in hand, the Minting Module can calculate the number of tokens to be minted for - each individual block by knowing the number of block in one years. + Given the annual inflation rate, the Minting Module calculates the exact amount of tokens to be generated for each + block, based on the total number of blocks in a year. diff --git a/proto/mint/v1beta1/mint.proto b/proto/mint/v1beta1/mint.proto index 05e74f0dd..fbd242489 100644 --- a/proto/mint/v1beta1/mint.proto +++ b/proto/mint/v1beta1/mint.proto @@ -7,21 +7,15 @@ import "gogoproto/gogo.proto"; option go_package = "github.com/okp4/okp4d/x/mint/types"; -// Minter represents the minting state within the blockchain. -// -// At each block, the minting module recalculates the annual inflation rate dynamically. It then determines the total -// amount of tokens to be provisioned for the upcoming year based on this rate. -// -// Additionally, the module computes the precise number of tokens to be minted for the current block, taking into account -// its position within the annual cycle. +// Minter holds the state of minting within the blockchain. message Minter { - // Represents the current annual inflation rate. + // Current annual inflation rate. string inflation = 1 [ (cosmos_proto.scalar) = "cosmos.Dec", (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec", (gogoproto.nullable) = false ]; - // Represents the current annual expected provisions. + // Current annual anticipated provisions. string annual_provisions = 2 [ (cosmos_proto.scalar) = "cosmos.Dec", (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec", @@ -29,18 +23,20 @@ message Minter { ]; } -// Params holds parameters for the mint module. +// Params defines the parameters for the mint module. message Params { option (gogoproto.goproto_stringer) = false; - // Type of coin to mint + // Denomination of the coin to be minted. string mint_denom = 1; - // Annual inflation coefficient + + // Annual inflation coefficient, influencing the inflation rate based on the bonded ratio. + // Values range from 0 to 1, with higher values indicating higher inflation. string inflation_coef = 2 [ (cosmos_proto.scalar) = "cosmos.Dec", (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec", (gogoproto.nullable) = false ]; - // Estimated blocks per year + // Estimated number of blocks per year. uint64 blocks_per_year = 3; } diff --git a/x/mint/types/mint.pb.go b/x/mint/types/mint.pb.go index c4176ab32..f8625cab2 100644 --- a/x/mint/types/mint.pb.go +++ b/x/mint/types/mint.pb.go @@ -25,17 +25,11 @@ var _ = math.Inf // proto package needs to be updated. const _ = proto.GoGoProtoPackageIsVersion3 // please upgrade the proto package -// Minter represents the minting state within the blockchain. -// -// At each block, the minting module recalculates the annual inflation rate dynamically. It then determines the total -// amount of tokens to be provisioned for the upcoming year based on this rate. -// -// Additionally, the module computes the precise number of tokens to be minted for the current block, taking into account -// its position within the annual cycle. +// Minter holds the state of minting within the blockchain. type Minter struct { - // Represents the current annual inflation rate. + // Current annual inflation rate. Inflation github_com_cosmos_cosmos_sdk_types.Dec `protobuf:"bytes,1,opt,name=inflation,proto3,customtype=github.com/cosmos/cosmos-sdk/types.Dec" json:"inflation"` - // Represents the current annual expected provisions. + // Current annual anticipated provisions. AnnualProvisions github_com_cosmos_cosmos_sdk_types.Dec `protobuf:"bytes,2,opt,name=annual_provisions,json=annualProvisions,proto3,customtype=github.com/cosmos/cosmos-sdk/types.Dec" json:"annual_provisions"` } @@ -72,13 +66,14 @@ func (m *Minter) XXX_DiscardUnknown() { var xxx_messageInfo_Minter proto.InternalMessageInfo -// Params holds parameters for the mint module. +// Params defines the parameters for the mint module. type Params struct { - // Type of coin to mint + // Denomination of the coin to be minted. MintDenom string `protobuf:"bytes,1,opt,name=mint_denom,json=mintDenom,proto3" json:"mint_denom,omitempty"` - // Annual inflation coefficient + // Annual inflation coefficient, influencing the inflation rate based on the bonded ratio. + // Values range from 0 to 1, with higher values indicating higher inflation. InflationCoef github_com_cosmos_cosmos_sdk_types.Dec `protobuf:"bytes,2,opt,name=inflation_coef,json=inflationCoef,proto3,customtype=github.com/cosmos/cosmos-sdk/types.Dec" json:"inflation_coef"` - // Estimated blocks per year + // Estimated number of blocks per year. BlocksPerYear uint64 `protobuf:"varint,3,opt,name=blocks_per_year,json=blocksPerYear,proto3" json:"blocks_per_year,omitempty"` }