diff --git a/proto/desmos/subspaces/v3/models.proto b/proto/desmos/subspaces/v3/models.proto index 085918e371..889f80cd90 100644 --- 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 index 21a1b44d2b..a8465b93a6 100644 --- 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 new file mode 100644 index 0000000000..ccce6402fb --- /dev/null +++ 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) \ No newline at end of file diff --git a/x/tokenfactory/spec/02-concepts.md b/x/tokenfactory/spec/02-concepts.md new file mode 100644 index 0000000000..eb866b99ba --- /dev/null +++ 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. \ No newline at end of file diff --git a/x/tokenfactory/spec/03-state.md b/x/tokenfactory/spec/03-state.md new file mode 100644 index 0000000000..672f579962 --- /dev/null +++ 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 | | authoritymetadata -> ProtocolBuffer(DenomAuthorityMetadata)` + +## Creator +The creator of a denomination is stored on the chain as follows: + +* `creator |
| -> ` + +## 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 new file mode 100644 index 0000000000..dd392f7727 --- /dev/null +++ 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. \ No newline at end of file diff --git a/x/tokenfactory/spec/05-events.md b/x/tokenfactory/spec/05-events.md new file mode 100644 index 0000000000..809d9b5626 --- /dev/null +++ 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 new file mode 100644 index 0000000000..7832fbfe5b --- /dev/null +++ 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"}` | \ No newline at end of file diff --git a/x/tokenfactory/spec/07-permissions.md b/x/tokenfactory/spec/07-permissions.md new file mode 100644 index 0000000000..7bcfd4327b --- /dev/null +++ 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) | \ No newline at end of file diff --git a/x/tokenfactory/spec/08-client.md b/x/tokenfactory/spec/08-client.md new file mode 100644 index 0000000000..cf7a6e017e --- /dev/null +++ b/x/tokenfactory/spec/08-client.md @@ -0,0 +1,125 @@ +--- +id: client +title: Client +sidebar_label: Client +slug: client +--- + +# Client + +## CLI + +A user can interact with the `x/tokenfactory` module using the following CLI commands. + +### Query + +The `query` command allows users to query the state of the module. + +```bash +desmos query tokenfactory --help +``` + +#### params +The `params` query command allows users to query for the module's parameters. + +```bash +desmos query tokenfactory params [flags] +``` + +Example: +```bash +desmos query tokenfactory params +``` + +Example output: +```yaml +params: + denom_creation_fee: + - amount: "10000000000" + denom: udaric +``` + +#### subspace-denoms +The `subspace-denoms` query command allows users to query for the denoms that have been created from within a given subspace. + +```bash +desmos query tokenfactory subspace-denoms [subspace-id] [flags] +``` + +Example: +```bash +desmos query tokenfactory subspace-denoms 1 +``` + +Example output: +```yaml +denoms: +- factory/desmos1cyjzgj9j7d2gdqk78pa0fgvfnlzradat3xsfpa/test +``` + +## gRPC +Users can query the `tokenfactory` module gRPC endpoints. + +### Params +The `Params` gRPC endpoint allows users to query the module's parameters. + +``` +desmos.tokenfactory.v1.Query/Params +``` + +Example: +```bash +grpcurl -plaintext localhost:9090 desmos.tokenfactory.v1.Query/Params +``` + +Example output: +```json +{ + "params": { + "denomCreationFee": [ + { + "denom": "udaric", + "amount": "10000000000" + } + ] + } +} +``` + +### SubspaceDenoms +The `SubspaceDenoms` gRPC endpoint allows users to query the denoms that have been created from within a given subspace. + +``` +desmos.tokenfactory.v1.Query/SubspaceDenoms +``` + +Example: +```bash +grpcurl -plaintext -d '{"subspace_id":1}' localhost:9090 desmos.tokenfactory.v1.Query/SubspaceDenoms +``` + +Example output: +```json +{ + "denoms": [ + "factory/desmos1cyjzgj9j7d2gdqk78pa0fgvfnlzradat3xsfpa/test" + ] +} +``` + +## REST +A user can query the `tokenfactory` module REST endpoints. + +### Params +The `Params` REST endpoint allows users to query the module's parameters. + +``` +/desmos/tokenfactory/v1/params +``` + +### SubspaceDenoms +The `SubspaceDenoms` REST endpoint allows users to query the denoms that have been created from within a given subspace. + +``` +/desmos/tokenfactory/v1/subspaces/{subspace_id}/denoms +``` \ No newline at end of file