From f3038b9e5568da45b115e8400d15cc18905aad1f Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sat, 2 Mar 2024 16:17:14 -0600 Subject: [PATCH] docs --- api/manifest/v1/genesis.pulsar.go | 2 +- proto/manifest/v1/genesis.proto | 2 +- x/manifest/spec/01_concepts.md | 37 +++++++++++++++++++++ x/manifest/spec/02_state.md | 53 +++++++++++++++++++++++++++++++ x/manifest/spec/README.md | 18 +++++++++++ x/manifest/types/genesis.pb.go | 2 +- 6 files changed, 111 insertions(+), 3 deletions(-) create mode 100644 x/manifest/spec/01_concepts.md create mode 100644 x/manifest/spec/02_state.md create mode 100644 x/manifest/spec/README.md diff --git a/api/manifest/v1/genesis.pulsar.go b/api/manifest/v1/genesis.pulsar.go index 363d89d..86fcdf5 100644 --- a/api/manifest/v1/genesis.pulsar.go +++ b/api/manifest/v1/genesis.pulsar.go @@ -2153,7 +2153,7 @@ func (x *StakeHolders) GetPercentage() int32 { return 0 } -// Inflation is the automatic inflation and distribution coins to the stake holders +// Inflation is the distribution coins to the stake holders type Inflation struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache diff --git a/proto/manifest/v1/genesis.proto b/proto/manifest/v1/genesis.proto index 1eaf5a8..be1fdc0 100644 --- a/proto/manifest/v1/genesis.proto +++ b/proto/manifest/v1/genesis.proto @@ -35,7 +35,7 @@ message StakeHolders { int32 percentage = 2; } -// Inflation is the automatic inflation and distribution coins to the stake holders +// Inflation is the distribution coins to the stake holders message Inflation { option (gogoproto.equal) = true; // if automatic inflation is enabled for distribution diff --git a/x/manifest/spec/01_concepts.md b/x/manifest/spec/01_concepts.md new file mode 100644 index 0000000..cd1fe44 --- /dev/null +++ b/x/manifest/spec/01_concepts.md @@ -0,0 +1,37 @@ + + +# Concepts + +## Manifest + +The Manifest module allows the chain admin(s) to set stakeholders and their percent of network rewards. These rewards can be made automatically on a set fixed amount per block, or manually if auto inflation is toggled off. + +## Update Stakeholders and Inflation + +**NOTE** This can only be run from the chain's PoA admin(s) addresses. + +```bash +# address_pairs is a comma delimited list of address and percent pairs in the micro format +# - `address:1_000_000,address2:99_000_000` = 2 addresses at 100%. +# +# inflation_per_year_coin is the amount of coins to give per year for automatic inflation +# - `5000000umfx` +# +manifestd tx manifest update-params [address_pairs] [automatic_inflation_enabled] [inflation_per_year_coin] +``` + +## Payout Stakeholders Manually + +**NOTE** This can only be run from the chain's PoA admin(s) addresses. +**NOTE** This may only be run when automatic inflation is off. If it is on, this transaction will always error out on execution. + +```bash +# coin_amount is the amount of coins to distribute to all stakeholders. This is then split up based off their split of the network distribution. +# - `5000000umfx` +# +# If you wish to payout to a different group than what current stakeholders are set, use a multi-message transaction to update-params, perform the payout, and update-params back to the original state. This can be done in 1 transaction. +# -https://docs.junonetwork.io/developer-guides/miscellaneous/multi-message-transaction +manifestd tx manifest stakeholder-payout [coin_amount] +``` diff --git a/x/manifest/spec/02_state.md b/x/manifest/spec/02_state.md new file mode 100644 index 0000000..75fe8a5 --- /dev/null +++ b/x/manifest/spec/02_state.md @@ -0,0 +1,53 @@ + + +# State + +## State Objects + +The `x/manifest` module only manages the following object in state: Params. This object holds all the required information for the module to operate. For automatic inflation, the x/mint modules `Params` is used to take the per year reward coins and divide it by the number of blocks per year, resulting in the per block reward amount. + +```proto +message Params { + option (amino.name) = "manifest/params"; + option (gogoproto.equal) = true; + option (gogoproto.goproto_stringer) = false; + + repeated StakeHolders stake_holders = 1; + + Inflation inflation = 2; +} + +// StakeHolders is the list of addresses and their percentage of the inflation distribution +message StakeHolders { + option (gogoproto.equal) = true; + + // manifest address that receives the distribution + string address = 1; + + // percentage is the micro denom % of tokens this address gets on a distribution. + // 100% = 100000000 total. so 1000000 = 1%. + int32 percentage = 2; +} + +// Inflation is the distribution coins to the stake holders +message Inflation { + option (gogoproto.equal) = true; + + // if auto payouts are done per block + bool automatic_enabled = 1; + + // amount of umfx tokens distributed per year + uint64 yearly_amount = 2; + + // the token to distribute (i.e. 'umfx') + string mint_denom = 3; +} +``` + +## State Transitions + +The following state transitions are possible: + +- Update params for stakeholders percent, and inflation values (denom, and automatic) \ No newline at end of file diff --git a/x/manifest/spec/README.md b/x/manifest/spec/README.md new file mode 100644 index 0000000..16984d0 --- /dev/null +++ b/x/manifest/spec/README.md @@ -0,0 +1,18 @@ +# `manifest` + +## Abstract + +This document specifies the internal `x/manifest` module of The Lifted Initiative, Manifest Ledger. + +The `x/manifest` module provides the following abilities: +- Setting a group of stakeholders that receive a set % of inflation +- Toggling Inflation from automatic and manual modes + +This inflation is not tied to a standard bonded ratio like typical proof-of-stake (PoS) systems, Instead it is up to chain admin(s) to decide given the nature of a proof-of-authority (PoA) chain. + +By using this module, token distributions can be delivered to select stakeholders within the bounds of certain set parameters + +## Contents + +1. **[Concepts](01_concepts.md)** +2. **[State](02_state.md)** \ No newline at end of file diff --git a/x/manifest/types/genesis.pb.go b/x/manifest/types/genesis.pb.go index 5c8168d..149c7c3 100644 --- a/x/manifest/types/genesis.pb.go +++ b/x/manifest/types/genesis.pb.go @@ -178,7 +178,7 @@ func (m *StakeHolders) GetPercentage() int32 { return 0 } -// Inflation is the automatic inflation and distribution coins to the stake holders +// Inflation is the distribution coins to the stake holders type Inflation struct { // if automatic inflation is enabled for distribution AutomaticEnabled bool `protobuf:"varint,1,opt,name=automatic_enabled,json=automaticEnabled,proto3" json:"automatic_enabled,omitempty"`