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] +```