docs: added tokenfactory module documentation

desmos-labs · Jul 10, 2023 · 0d90981 · 0d90981
1 parent 5a4b7e2
commit 0d90981
Show file tree

Hide file tree

Showing 10 changed files with 379 additions and 17 deletions.
diff --git a/proto/desmos/subspaces/v3/models.proto b/proto/desmos/subspaces/v3/models.proto
@@ -17,13 +17,13 @@ message Subspace {
 
   // Unique id that identifies the subspace
   uint64 id = 1
-  [(gogoproto.customname) = "ID", (gogoproto.moretags) = "yaml:\"id\""];
+      [ (gogoproto.customname) = "ID", (gogoproto.moretags) = "yaml:\"id\"" ];
 
   // Human-readable name of the subspace
-  string name = 2 [(gogoproto.moretags) = "yaml:\"name\""];
+  string name = 2 [ (gogoproto.moretags) = "yaml:\"name\"" ];
 
   // Optional description of this subspace
-  string description = 3 [(gogoproto.moretags) = "yaml:\"description\""];
+  string description = 3 [ (gogoproto.moretags) = "yaml:\"description\"" ];
 
   // Represents the treasury account that is associated with the subspace
   string treasury = 4 [
@@ -74,7 +74,7 @@ message Section {
 
   // Unique id of the section within the subspace
   uint32 id = 2
-  [(gogoproto.customname) = "ID", (gogoproto.moretags) = "yaml:\"id\""];
+      [ (gogoproto.customname) = "ID", (gogoproto.moretags) = "yaml:\"id\"" ];
 
   // (optional) Id of the parent section
   uint32 parent_id = 3 [
@@ -83,10 +83,10 @@ message Section {
   ];
 
   // Name of the section within the subspace
-  string name = 4 [(gogoproto.moretags) = "yaml:\"name\""];
+  string name = 4 [ (gogoproto.moretags) = "yaml:\"name\"" ];
 
   // (optional) Description of the section
-  string description = 5 [(gogoproto.moretags) = "yaml:\"description\""];
+  string description = 5 [ (gogoproto.moretags) = "yaml:\"description\"" ];
 }
 
 // UserGroup represents a group of users
@@ -108,13 +108,13 @@ message UserGroup {
 
   // Unique id that identifies the group
   uint32 id = 3
-  [(gogoproto.customname) = "ID", (gogoproto.moretags) = "yaml:\"id\""];
+      [ (gogoproto.customname) = "ID", (gogoproto.moretags) = "yaml:\"id\"" ];
 
   // Human-readable name of the user group
-  string name = 4 [(gogoproto.moretags) = "yaml:\"name\""];
+  string name = 4 [ (gogoproto.moretags) = "yaml:\"name\"" ];
 
   // Optional description of this group
-  string description = 5 [(gogoproto.moretags) = "yaml:\"description\""];
+  string description = 5 [ (gogoproto.moretags) = "yaml:\"description\"" ];
 
   // Permissions that will be granted to all the users part of this group
   repeated string permissions = 6 [
@@ -128,10 +128,10 @@ message UserPermission {
   option (gogoproto.equal) = true;
   option (gogoproto.goproto_stringer) = true;
 
-  uint64 subspace_id = 1 [(gogoproto.customname) = "SubspaceID"];
-  uint32 section_id = 2 [(gogoproto.customname) = "SectionID"];
-  string user = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-  repeated string permissions = 4 [(gogoproto.castrepeated) = "Permissions"];
+  uint64 subspace_id = 1 [ (gogoproto.customname) = "SubspaceID" ];
+  uint32 section_id = 2 [ (gogoproto.customname) = "SectionID" ];
+  string user = 3 [ (cosmos_proto.scalar) = "cosmos.AddressString" ];
+  repeated string permissions = 4 [ (gogoproto.castrepeated) = "Permissions" ];
 }
 
 // Grant represents a grant to a user or a group

diff --git a/proto/desmos/tokenfactory/v1beta1/models.proto b/proto/desmos/tokenfactory/v1beta1/models.proto
@@ -6,13 +6,12 @@ import "cosmos_proto/cosmos.proto";
 
 option go_package = "github.com/desmos-labs/desmos/v5/x/tokenfactory/types";
 
-// DenomAuthorityMetadata specifies metadata for addresses that have specific
-// capabilities over a token factory denom. Right now there is only one Admin
-// permission, but is planned to be extended to the future.
+// DenomAuthorityMetadata contains the metadata for a single token denom.
 message DenomAuthorityMetadata {
   option (gogoproto.equal) = true;
 
-  // Can be empty for no admin, or a valid osmosis address
+  // Admin of the denomination.
+  // Can be empty for no admin, or a valid Desmos address
   string admin = 1 [
     (gogoproto.moretags) = "yaml:\"admin\"",
     (cosmos_proto.scalar) = "cosmos.AddressString"

diff --git a/x/tokenfactory/spec/01-overview.md b/x/tokenfactory/spec/01-overview.md
@@ -0,0 +1,37 @@
+---
+id: overview
+title: Overview
+sidebar_label: Overview
+slug: overview
+---
+
+# `x/tokenfactory`
+
+## Abstract
+This document specifies the tokenfactory module of Desmos.
+
+This module allows subspace admins to create new token denominations that can later be used as fee tokens inside a subspace.
+
+This module's implementation is derived from the [Osmosis `x/tokenfactory` module](https://github.com/osmosis-labs/osmosis/tree/main/x/tokenfactory). Instead of forking it, we chose to replicate the implementation. This decision was made because Osmosis is built on a custom version of the Cosmos SDK, which would have caused significant challenges in maintaining the codebase. However, if the module is added to a repository that allows for easier forking, we are open to considering it.
+
+## Contents
+1. **[Concepts](02-concepts.md)**
+   - [DenomAuthorityMetadata](02-concepts.md#denomauthoritymetadata)
+2. **[State](03-state.md)**
+   - [DenomAuthority](03-state.md#denomauthority)
+   - [DenomAuthorityMetadata](03-state.md#denomauthoritymetadata)
+   - [Params](03-state.md#params)
+3. **[Msg Service](04-messages.md)**
+   - [Msg/CreateDenom](04-messages.md#msgcreatedenom)
+   - [Msg/Mint](04-messages.md#msgmint)
+   - [Msg/Burn](04-messages.md#msgburn)
+   - [Msg/SetDenomMetadata](04-messages.md#msgsetdenommetadata)
+   - [Msg/UpdateParams](04-messages.md#msgupdateparams)
+4. **[Events](05-events.md)**
+   - [Handlers](05-events.md#handlers)
+5. **[Params](06-params.md)**
+6. **[Permissions](07-permissions.md)**
+7. **[Client](08-client.md)**
+   - [CLI](08-client.md#cli)
+   - [gRPC](08-client.md#grpc)
+   - [REST](08-client.md#rest)
diff --git a/x/tokenfactory/spec/02-concepts.md b/x/tokenfactory/spec/02-concepts.md
@@ -0,0 +1,16 @@
+---
+id: concepts
+title: Concepts
+sidebar_label: Concepts
+slug: concepts
+---
+
+# Concepts
+
+## DenomAuthorityMetadata
+
+The `DenomAuthorityMetadata` contains the metadata about a single denomination. 
+
+### Admin 
+
+Address of the manager of the denomination. If empty, the denomination is not managed by anyone.
diff --git a/x/tokenfactory/spec/03-state.md b/x/tokenfactory/spec/03-state.md
@@ -0,0 +1,24 @@
+---
+id: state
+title: State
+sidebar_label: State
+slug: state
+---
+
+# State
+
+## DenomAuthorityMetadata
+The authority metadata of various denominations are stored on the chain as follows:
+
+* `denoms | <Denom> | authoritymetadata -> ProtocolBuffer(DenomAuthorityMetadata)`
+
+## Creator
+The creator of a denomination is stored on the chain as follows:
+
+* `creator | <Address> | <Denom> -> <Denom>`
+
+## Params
+The params of the module are stored on the chain as follows:
+
+* `params -> ProtocolBuffer(Params)`
+
diff --git a/x/tokenfactory/spec/04-messages.md b/x/tokenfactory/spec/04-messages.md
@@ -0,0 +1,68 @@
+---
+id: messages
+title: Messages
+sidebar_label: Messages
+slug: messages
+---
+
+# Msg Service
+
+## Msg/CreateDenom
+A token denomination can be created with a `MsgCreateDenom`. In order to prevent spam, a fee is required to be paid from the subspace treasury in order to create a new denomination. Such fee's amount is set inside the module's params and can be updated by the chain governance if the community decides to do so.
+
+```js reference
+https://github.com/desmos-labs/desmos/blob/master/proto/desmos/tokenfactory/v1beta1/msgs.proto#L55-78
+```
+
+It's expected to fail if:
+* the subspace does not exist;
+* the provided denomination is invalid;
+* the sender does not have the permission to mint tokens inside the subspace;
+* the sender does not have enough balance to pay the creation fee.
+
+## Msg/Mint
+The admin of a token denomination can mint more tokens using a `MsgMint`.
+
+```js reference
+https://github.com/desmos-labs/desmos/blob/master/proto/desmos/tokenfactory/v1beta1/msgs.proto#L88-116
+```
+
+It's expected to fail if:
+* the subspace does not exist;
+* the provided amount does not match the existing denomination;
+* the sender does not have the permissions to mint more tokens of the provided denomination.
+
+## Msg/Burn
+The admin of a token denomination can burn tokens using a `MsgBurn`.
+
+```js reference
+https://github.com/desmos-labs/desmos/blob/master/proto/desmos/tokenfactory/v1beta1/msgs.proto#L123-151
+```
+
+It's expected to fail if:
+* the subspace does not exist;
+* the sender does not have the permissions to burn tokens of the provided denomination.
+
+## Msg/SetDenomMetadata
+The admin of a token denomination can set the metadata of the denomination using a `MsgSetDenomMetadata`.
+
+```js reference
+https://github.com/desmos-labs/desmos/blob/master/proto/desmos/tokenfactory/v1beta1/msgs.proto#L158-179
+```
+
+It's expected to fail if:
+* the subspace does not exist;
+* the sender does not have the permissions to set the metadata of the provided denomination;
+* the provided metadata is invalid.
+
+
+## Msg/UpdateParams
+The `MsgUpdateParams` can be used to update the overall module's params.
+
+```js reference
+https://github.com/desmos-labs/desmos/blob/master/proto/desmos/tokenfactory/v1beta1/msgs.proto#L191-213
+```
+
+It's expected to fail if:
+* the provided authority is not the address of the `x/gov` module;
+* the provided params are invalid.
diff --git a/x/tokenfactory/spec/05-events.md b/x/tokenfactory/spec/05-events.md
@@ -0,0 +1,64 @@
+---
+id: events
+title: Events
+sidebar_label: Events
+slug: events
+---
+
+# Events
+
+The tokenfactory module emits the following events:
+
+## Handlers
+
+### MsgCreateDenom
+
+| **Type**     | **Attribute Key** | **Attribute Value**                   | 
+|:-------------|:------------------|:--------------------------------------|
+| create_denom | subspace_id       | {subspaceID}                          |
+| create_denom | creator           | {userAddress}                         |
+| create_denom | new_token_denom   | {newTokenDenom}                       |
+| message      | module            | subspaces                             |
+| message      | action            | desmos.tokenfactory.v1.MsgCreateDenom |
+| message      | sender            | {userAddress}                         |
+
+## MsgMint
+
+| **Type** | **Attribute Key** | **Attribute Value**            | 
+|:---------|:------------------|:-------------------------------|
+| tf_mint  | subspace_id       | {subspaceID}                   |
+| tf_mint  | mint_to_address   | {subspaceTreasuryAddress}      |
+| tf_mint  | amount            | {tokenAmount}                  |
+| message  | module            | subspaces                      |
+| message  | action            | desmos.tokenfactory.v1.MsgMint |
+| message  | sender            | {userAddress}                  |
+
+## MsgBurn
+
+| **Type** | **Attribute Key** | **Attribute Value**            | 
+|:---------|:------------------|:-------------------------------|
+| tf_burn  | subspace_id       | {subspaceID}                   |
+| tf_burn  | burn_from_address | {subspaceTreasuryAddress}      |
+| tf_burn  | amount            | {tokenAmount}                  |
+| message  | module            | subspaces                      |
+| message  | action            | desmos.tokenfactory.v1.MsgBurn |
+| message  | sender            | {userAddress}                  |
+
+## MsgSetDenomMetadata
+
+| **Type**           | **Attribute Key** | **Attribute Value**                        | 
+|:-------------------|:------------------|:-------------------------------------------|
+| set_denom_metadata | subspace_id       | {subspaceID}                               |
+| set_denom_metadata | denom             | {denom}                                    |
+| set_denom_metadata | denom_metadata    | {denomMetadata}                            |
+| message            | module            | subspaces                                  |
+| message            | action            | desmos.tokenfactory.v1.MsgSetDenomMetadata |
+| message            | sender            | {userAddress}                              |
+
+## MsgUpdateParams
+
+| **Type** | **Attribute Key** | **Attribute Value**                    | 
+|:---------|:------------------|:---------------------------------------|
+| message  | module            | subspaces                              |
+| message  | action            | desmos.tokenfactory.v1.MsgUpdateParams |
+| message  | sender            | {userAddress}                          |
diff --git a/x/tokenfactory/spec/06-params.md b/x/tokenfactory/spec/06-params.md
@@ -0,0 +1,14 @@
+---
+id: params
+title: Parameters
+sidebar_label: Parameters
+slug: params
+---
+
+# Parameters
+
+The tokenfactory module contains the following parameters:
+
+| Key              | Type       | Example                                    |
+|------------------|------------|--------------------------------------------|
+| DenomCreationFee | `sdk.Coin` | `{"amount": "1000000", "denom": "udaric"}` |
diff --git a/x/tokenfactory/spec/07-permissions.md b/x/tokenfactory/spec/07-permissions.md
@@ -0,0 +1,15 @@
+---
+id: permissions
+title: Permissions
+sidebar_label: Permissions
+slug: permissions
+---
+
+# Permissions
+
+Based on which `x/tokenfactory` related action your users want to perform, they need to be granted with one or more of
+the following permissions.
+
+| **Permission Value**            | **Permission Description**                                                     | 
+|:--------------------------------|:-------------------------------------------------------------------------------|
+| `MANAGE_CUSTOM_SUBSPACE_TOKENS` | Allows to manage a subspace's custom denoms (create, mint, burn, set metadata) |