From 68a76273e6e178836aa6a2977e853a9e70feeb5f Mon Sep 17 00:00:00 2001 From: "Felix C. Morency" <1102868+fmorency@users.noreply.github.com> Date: Thu, 25 Jul 2024 10:09:35 -0400 Subject: [PATCH 1/3] fix: test node script --- scripts/test_node.sh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/test_node.sh b/scripts/test_node.sh index c7d80bf..3c5db20 100644 --- a/scripts/test_node.sh +++ b/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 From 7475caf9ee05fbd3bdd3e7338b2b7c5472eba307 Mon Sep 17 00:00:00 2001 From: "Felix C. Morency" <1102868+fmorency@users.noreply.github.com> Date: Thu, 25 Jul 2024 10:09:41 -0400 Subject: [PATCH 2/3] fix(make): unused command --- Makefile | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/Makefile b/Makefile index e0871bd..ba79641 100644 --- a/Makefile +++ b/Makefile @@ -126,10 +126,6 @@ test: @echo "--> Running tests" go test -v ./... -test-integration: - @echo "--> Running integration tests" - cd integration; go test -v ./... - coverage: ## Run coverage report @echo "--> Running coverage" @go test -race -cpu=$$(nproc) -covermode=atomic -coverprofile=coverage.out $$(go list ./...) ./interchaintest/... -coverpkg=github.com/strangelove-ventures/tokenfactory/... > /dev/null 2>&1 @@ -144,7 +140,7 @@ coverage: ## Run coverage report @rm coverage.out @echo "--> Running coverage complete" -.PHONY: test test-integration coverage +.PHONY: test coverage ################## ### Protobuf ### From 5481ee3fbe6a19c09f3689f6f2333eaa4315de4e Mon Sep 17 00:00:00 2001 From: "Felix C. Morency" <1102868+fmorency@users.noreply.github.com> Date: Thu, 25 Jul 2024 10:09:47 -0400 Subject: [PATCH 3/3] doc: module documentation --- README.md | 259 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 258 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0b2fd64..ad1b6cd 100644 --- a/README.md +++ b/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] +```