Token factory documentation

osmosis-labs · May 19, 2022 · 90db905 · 90db905
1 parent 82e58f8
commit 90db905
Showing 1 changed file with 71 additions and 0 deletions.
diff --git a/x/tokenfactory/README.md b/x/tokenfactory/README.md
@@ -16,3 +16,74 @@ created denom. Once a denom is created, the original creator is given
     accounts using the authz module. The `ChangeAdmin` functionality,
     allows changing the master admin account, or even setting it to
     `""`, meaning no account has admin privileges of the asset.
+
+
+## Messages
+
+### CreateDenom
+- Creates a denom of `factory/{creator address}/{nonce}` given the denom creator address and the denom nonce. The case a denom has a slash in its nonce is handled within the module.
+``` {.go}
+message MsgCreateDenom {
+  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
+  string nonce = 2 [ (gogoproto.moretags) = "yaml:\"nonce\"" ];
+}
+```
+
+**State Modifications:**
+- Fund community pool with the denom creation fee from the creator address, set in `Params`
+- Set `DenomMetaData` via bank keeper
+- Set `AuthorityMetadata` for the given denom to store the admin for the created denom `factory/{creator address}/{nonce}`. Admin is automatically set as the Msg sender
+- Add denom to the `CreatorPrefixStore`, where a state of denoms created per creator is kept
+
+### Mint
+- Minting of a specific denom is only allowed for the creator of the denom registered during `CreateDenom`
+``` {.go}
+message MsgMint {
+  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
+  cosmos.base.v1beta1.Coin amount = 2 [
+    (gogoproto.moretags) = "yaml:\"amount\"",
+    (gogoproto.nullable) = false
+  ];
+}
+```
+
+**State Modifications:**
+- Saftey check the following
+  - Check that the denom minting is created via `tokenfactory` module
+  - Check that the sender of the message is the admin of the denom
+- Mint designated amount of tokens for the denom via `bank` module
+
+
+
+### Burn
+- Burning of a specific denom is only allowed for the creator of the denom registered during `CreateDenom`
+``` {.go}
+message MsgBurn {
+  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
+  cosmos.base.v1beta1.Coin amount = 2 [
+    (gogoproto.moretags) = "yaml:\"amount\"",
+    (gogoproto.nullable) = false
+  ];
+}
+```
+
+**State Modifications:**
+- Saftey check the following
+  - Check that the denom minting is created via `tokenfactory` module
+  - Check that the sender of the message is the admin of the denom
+- Burn designated amount of tokens for the denom via `bank` module
+
+
+### ChangeAdmin
+- Burning of a specific denom is only allowed for the creator of the denom registered during `CreateDenom`
+``` {.go}
+message MsgChangeAdmin {
+  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
+  string denom = 2 [ (gogoproto.moretags) = "yaml:\"denom\"" ];
+  string newAdmin = 3 [ (gogoproto.moretags) = "yaml:\"new_admin\"" ];
+}
+```
+
+**State Modifications:**
+- Check that sender of the message is the admin of denom
+- Modify `AuthorityMetadata` state entry to change the admin of the denom