Skip to content

docs(examples): add end-to-end x/tokenfactory minting example (create denom → mint → transfer → burn) #39

@danbaruka

Description

@danbaruka

Summary

The chain exposes x/tokenfactory — one of the most useful modules for builders launching their own tokens on Safrochain — but there is no walkthrough showing a complete lifecycle: creating a denom, minting supply, transferring it, updating metadata, and burning. New token issuers have to discover the flow from the Go keeper code or assume it works the same as the upstream Osmosis implementation.

Goal

Add examples/tokenfactory/ with a runnable shell script (or justfile / Makefile) plus a narrated README.md that demonstrates the full flow against a local Safrochain node.

Suggested flow to demonstrate

  1. Setup — start a local node, create two keys (creator, recipient), fund them with usaf
  2. Create a denomsafrochaind tx tokenfactory create-denom <subdenom> and show the resulting full denom (factory/<creator-addr>/<subdenom>) — also show the creation fee from chain params
  3. Set metadatatx tokenfactory set-denom-metadata … (name, symbol, description, exponents) so it renders nicely in wallets and explorers
  4. Minttx tokenfactory mint <amount><denom> to the creator
  5. Mint totx tokenfactory mint-to <recipient> <amount><denom> (if exposed) to demonstrate direct minting
  6. Transfer — plain tx bank send to show the new denom behaves like any bank coin
  7. Burntx tokenfactory burn <amount><denom> and burn-from if available
  8. Change admintx tokenfactory change-admin <new-admin> and explain why this is the on-chain primitive for transferring control / renouncing admin (set to a burn address)
  9. Queryq bank balances, q bank denom-metadata, q tokenfactory denom-authority-metadata, q tokenfactory denoms-from-creator
  10. Cleanup — optional teardown

Each step should print the exact CLI invocation, the expected JSON response (trimmed), and a one-line explanation of what just happened.

Suggested file layout

```
examples/tokenfactory/
README.md # narrated walkthrough
run.sh # idempotent script that executes the whole flow
.env.example # CHAIN_ID, NODE, KEYRING_BACKEND, etc.
```

Bonus: link with CosmWasm

Add a short closing section showing how a CosmWasm contract can become the admin of a tokenfactory denom and mint programmatically — this is how most real-world projects on Cosmos issue tokens today. (Cross-references the CosmWasm examples in the companion issue.)

Why this matters

  • Token issuance is the Bump github.com/cosmos/cosmos-db from 1.1.1 to 1.1.3 #1 onboarding question for any new chain with permissionless tokenfactory. A copy-pasteable script answers it in 5 minutes instead of 5 hours.
  • Surfaces chain-specific params — denom creation fee, allowed subdenom format, admin model — which are otherwise buried in genesis or keeper code.
  • Shows the chain works end-to-end. Running this script in CI on every commit is a cheap, high-signal smoke test that bank + tokenfactory + fees + signing all integrate correctly.
  • Sets the on-ramp for projects building on Safrochain. Stablecoins, points programs, NFT-payment tokens, liquidity-mining rewards — all start with create-denom.

Acceptance criteria

  • examples/tokenfactory/run.sh runs cleanly against a fresh local node and exits 0
  • README.md includes every command from the script with expected output excerpts
  • Fees and denom-creation cost are read from on-chain params, not hard-coded, so the example survives param changes
  • At least one query example shown for every state change (mint → balance, set-metadata → denom-metadata, change-admin → denom-authority-metadata)
  • Bonus section documenting CosmWasm-as-admin pattern (can be a follow-up PR)

Why this is a good first issue

The work is mostly shell + Markdown, the chain primitives are stable, and it produces a deliverable every future Safrochain token issuer will use. A newcomer can ship this without writing Go.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or requestgood first issueGood for newcomershelp wantedExtra attention is needed

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions