doc: readme (#18)

* fix: test node script

* fix(make): unused command

* doc: module documentation

Makefile

@@ -126,10 +126,6 @@ test:
 	@echo "--> Running tests"
 	go test -v ./...
 
-test-integration:
-	@echo "--> Running integration tests"
-	cd integration; go test -v ./...
-
 COV_ROOT="/tmp/tokenfactory-coverage"
 COV_UNIT_E2E="${COV_ROOT}/unit-e2e"
 COV_SIMULATION="${COV_ROOT}/simulation"
@@ -170,7 +166,7 @@ coverage: ## Run coverage report
 	@rm -rf ${COV_UNIT_E2E}/* ${COV_SIMULATION}/*
 	@echo "--> Running coverage complete"
 
-.PHONY: test test-integration coverage
+.PHONY: test coverage
 
 ##################
 ###  Protobuf  ###

README.md

@@ -1 +1,258 @@
-# Cosmos-SDK x/TokenFactory
+# Token Factory
+
+The `tokenfactory` module allows any account to create a new token with the name `factory/{creator address}/{subdenom}`. Because tokens are namespaced by creator address, this allows token minting to be permissionless, due to not needing to resolve name collisions. A single account can create multiple denoms, by providing a unique subdenom for each created denom. Once a denom is created, the original creator is given "admin" privileges over the asset. This allows them to:
+
+- Mint their denom to any account
+- Burn their denom from any account
+- Create a transfer of their denom between any two accounts
+- Change the admin. The `ChangeAdmin` functionality allows changing the master admin account, or even setting it to "", meaning no account has admin privileges of the asset.
+
+## References
+
+- Osmosis Labs [TokenFactory](https://github.com/osmosis-labs/osmosis/tree/main/x/tokenfactory)
+
+## Installation
+
+This repository provides the `tokend` application, a simple command-line application that demonstrates the functionality of the `tokenfactory` module. To build and install the `tokend` application, run:
+
+```bash
+make install
+```
+
+The application can be run with the following command:
+
+```bash
+tokend
+```
+
+## Test Node
+
+To run a test node with the `tokenfactory` module, run:
+
+```bash
+make install
+CHAIN_ID="local-1" HOME_DIR="~/.tokenfactory" TIMEOUT_COMMIT="500ms" CLEAN=true sh scripts/test_node.sh
+```
+
+## Usage
+
+The `tokend` application provides the following `tokenfactory` transactions:
+
+- `create-denom`: Create a new denom with the name `factory/{creator address}/{subdenom}`.
+- `mint`: Mint tokens to your address. You must be the admin of the denom to mint tokens.
+- `mint-to`: Mint tokens to another address. You must be the admin of the denom to mint tokens.
+- `burn`: Burn tokens from your address. You must be the admin of the denom to burn tokens.
+- `burn-from`: Burn tokens from another address. You must be the admin of the denom to burn tokens.
+- `force-transfer`: Transfer tokens between two addresses. You must be the admin of the denom to transfer tokens.
+- `change-admin`: Change the admin of the denom. You must be the admin of the denom to change the admin.
+- `modify-metadata`: Modify the metadata of the denom. You must be the admin of the denom to modify the metadata.
+
+and the following queries:
+
+- `params`: Get the tokenfactory module parameters.
+- `denom-authority-metadata`: Get the authority metadata of a denom.
+- `denoms-from-creator`: Returns a list of all denoms created by a given creator.
+
+## Testing
+
+To test the `tokenfactory` module, run:
+
+```bash
+make test
+```
+
+To run the `tokenfactory` module's end-to-end tests, run:
+```bash
+make local-image
+make ictest-tokenfactory
+```
+
+## Coverage
+
+To generate the coverage report of the `tokenfactory` module, run:
+
+```bash
+make local-image
+make coverage
+```
+
+## Simulation
+
+To run the `tokenfactory` module's full application simulation tests, run:
+
+```bash
+make sim-full-app
+```
+
+To run the `tokenfactory` simulation after state import test, run:
+
+```bash
+make sim-after-import
+```
+
+To run the `tokenfactory` application determinism simulation, run:
+
+```bash
+make sim-app-determinism
+```
+
+Append `-random` to the end of the commands above to run the simulation with a random seed, e.g., `make sim-full-app-random`.
+
+## Examples
+
+### Create Denom
+
+```bash
+# Usage:
+#   tokend tx tokenfactory create-denom [subdenom] [flags]
+tokend tx tokenfactory create-denom utest --from alice
+
+# Query the newly created token
+# cosmos1... is the creator address of the denom (alice) 
+tokend q tokenfactory denoms-from-creator cosmos1...
+denoms:
+- factory/cosmos1.../utest
+
+```
+
+### Modify Metadata
+
+```bash
+# Usage:
+#   tokend tx tokenfactory modify-metadata [denom] [ticker-symbol] [description] [exponent] [flags]
+
+# Modify the metadata of the utest denom
+# cosmos1... is the creator address of the denom (alice)
+# The ticker symbol is TST and the description is "My token description"
+# The denom exponent is 6
+tokend tx tokenfactory modify-metadata factory/cosmos1.../utest TST "My token description" 6 --from alice
+
+# Query the authority metadata of the factory/cosmos1.../utest denom
+tokend q tokenfactory denom-authority-metadata factory/cosmos1.../utest
+authority_metadata:
+  admin: cosmos1...
+
+# Query the denom metadata from the bank module
+tokend q bank denom-metadata factory/cosmos1.../utest
+metadata:
+  base: factory/cosmos1.../utest
+  denom_units:
+  - aliases:
+    - TST
+    denom: factory/cosmos1.../utest
+  - aliases:
+    - factory/cosmos1.../utest
+    denom: TST
+    exponent: 6
+  description: My token description
+  display: TST
+  name: factory/cosmos1.../utest
+  symbol: TST
+```
+
+### Mint
+
+```bash
+# Usage:
+#   tokend tx tokenfactory mint [amount] [flags]
+
+# Mint 1000 tokens to alice
+# cosmos1... is the creator address of the denom (alice)
+tokend tx tokenfactory mint 1000factory/cosmos1.../utest --from alice
+
+# Query the account balance of alice
+tokend q bank balance cosmos1... factory/cosmos1.../utest
+balance:
+  amount: "1000"
+  denom: factory/cosmos1.../utest
+```
+
+### Mint To
+
+```bash
+# Usage:
+#   tokend tx tokenfactory mint-to [address] [amount] [flags]
+
+# Mint 2000 tokens to bob
+# cosmos1... is the creator address of the denom (alice)
+tokend tx tokenfactory mint-to [bob-addr] 2000factory/cosmos1.../utest --from alice
+
+# Query the account balance of bob
+tokend q bank balance [bob-addr] factory/cosmos1.../utest
+balance:
+  amount: "2000"
+  denom: factory/cosmos1.../utest
+```
+
+### Burn
+
+```bash
+# Usage:
+#   tokend tx tokenfactory burn [amount] [flags]
+
+# Burn 500 tokens from alice
+# cosmos1... is the creator address of the denom (alice)
+tokend tx tokenfactory burn 500factory/cosmos1.../utest --from alice
+
+# Query the account balance of alice
+tokend q bank balance cosmos1... factory/cosmos1.../utest
+balance:
+  amount: "500"
+  denom: factory/cosmos1.../utest
+```
+
+### Burn From
+
+```bash
+# Usage:
+#   tokend tx tokenfactory burn-from [address] [amount] [flags]
+
+# Burn 500 tokens from bob
+# cosmos1... is the creator address of the denom (alice)
+tokend tx tokenfactory burn-from [bob-addr] 500factory/cosmos1.../utest --from alice
+
+# Query the account balance of bob
+tokend q bank balance [bob-addr] factory/cosmos1.../utest
+balance:
+  amount: "1500"
+  denom: factory/cosmos1.../utest
+```
+
+### Force Transfer
+
+```bash
+# Usage:
+#   tokend tx tokenfactory force-transfer [amount] [transfer-from-address] [transfer-to-address] [flags]
+
+# Transfer 500 tokens from bob to alice
+# cosmos1... is the creator address of the denom (alice)
+tokend tx tokenfactory force-transfer 50factory/cosmos1.../utest [bob-addr] cosmos1... --from alice
+
+# Query the account balance of alice
+tokend q bank balance cosmos1... factory/cosmos1.../utest
+balance:
+  amount: "550"
+  denom: factory/cosmos1.../utest
+
+# Query the account balance of bob
+tokend q bank balance [bob-addr] factory/cosmos1.../utest
+balance:
+  amount: "1450"
+  denom: factory/cosmos1.../utest
+```
+
+### Change Admin
+
+```bash
+# Usage:
+#   tokend tx tokenfactory change-admin [denom] [new-admin-address] [flags]
+
+# Change the admin of the utest denom to bob
+# cosmos1... is the creator address of the denom (alice)
+tokend tx tokenfactory change-admin factory/cosmos1.../utest [bob-addr] --from alice
+
+# Query the authority metadata of the factory/cosmos1.../utest denom
+tokend q tokenfactory denom-authority-metadata factory/cosmos1.../utest
+authority_metadata:
+  admin: [bob-addr]
+```

scripts/test_node.sh

@@ -69,15 +69,15 @@ from_scratch () {
 
   # TokenFactory
   update_test_genesis '.app_state["tokenfactory"]["params"]["denom_creation_fee"]=[]'
-  update_test_genesis '.app_state["tokenfactory"]["params"]["denom_creation_gas_consume"]=2000000'
+  update_test_genesis '.app_state["tokenfactory"]["params"]["denom_creation_gas_consume"]=0'
 
   # Allocate genesis accounts
-  BINARY genesis add-genesis-account $KEY 1000000ustake,10000000token,1000utest --keyring-backend $KEYRING
-  BINARY genesis add-genesis-account $KEY2 100000000000000000000000token,1000utest --keyring-backend $KEYRING
+  BINARY genesis add-genesis-account $KEY 1000000ustake,10000000token --keyring-backend $KEYRING
+  BINARY genesis add-genesis-account $KEY2 100000000000000000000000token --keyring-backend $KEYRING
 
   # must have at least 1 full token to be valid to start.
   GenTxFlags="--commission-rate=0.0 --commission-max-rate=1.0 --commission-max-change-rate=0.1"
-  BINARY genesis gentx $KEY 1000000ustake --keyring-backend $KEYRING --chain-id $CHAIN_ID $GenTxFlags
+  BINARY genesis gentx $KEY 1000000token --keyring-backend $KEYRING --chain-id $CHAIN_ID $GenTxFlags
 
   # Collect genesis tx
   BINARY genesis collect-gentxs --home=$HOME_DIR