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.

Supported Versions

References

• Osmosis Labs 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:

make install

The application can be run with the following command:

tokend

Test Node

To run a test node with the tokenfactory module, run:

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:

make test

To run the tokenfactory module's end-to-end tests, run:

make local-image
make ictest-tokenfactory

Coverage

To generate the coverage report of the tokenfactory module, run:

make local-image
make coverage

Simulation

To run the tokenfactory module's full application simulation tests, run:

make sim-full-app

To run the tokenfactory simulation after state import test, run:

make sim-after-import

To run the tokenfactory application determinism simulation, run:

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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]