Technical Explanation
The Token Factory module enables users to create and manage custom tokens on Neutron. This module was adapted from Osmosis Labs codebase and provides a framework for token creation, administration, and lifecycle management.Core Concepts
Token Denomination Format
Token Factory creates tokens with a standardized denomination format:factory/
: Required prefix identifying Token Factory tokens{creator_address}
: Bech32 address of the token creator{subdenom}
: Custom subdenom chosen by creator (max 44 characters)
factory/neutron1abc.../utoken
factory/neutron1xyz.../shares
factory/neutron1def.../points
Token Administration
Each token has an admin who controls its lifecycle: Admin Powers:- Mint new tokens to any address
- Burn existing tokens from any address
- Change token admin
- Set token metadata via bank keeper
- Configure before-send hooks
- Force transfers (bypass hooks)
- Admin can be transferred to another address
- Admin can be set to empty string (renouncing control)
- Once renounced, admin powers cannot be restored
Token Lifecycle
1. Token Creation
Process:- User submits
MsgCreateDenom
with subdenom - System validates subdenom using
GetTokenDenom()
and SDKValidateDenom()
- Creation fee is charged (if configured) and sent to fee collector
- Full denomination is generated:
factory/{creator}/{subdenom}
- Creator becomes initial admin
AuthorityMetadata
is set for the denom- Denom is added to
CreatorPrefixStore
- Subdenom maximum length: 44 characters
- Creator address maximum length: 75 characters (59 + 16 HRP length)
- Creator address cannot contain ”/” characters
- Must pass SDK denomination validation
2. Token Supply Management
Minting:- Only admin can mint tokens via
MsgMint
- Tokens minted to
mint_to_address
(defaults to sender if empty) - Uses bank keeper’s mint functionality
- Only admin can burn tokens via
MsgBurn
- Tokens burned from
burn_from_address
(defaults to sender if empty) - Cannot burn from module accounts (
ErrBurnFromModuleAccount
) - Uses bank keeper’s burn functionality
3. Token Metadata
Metadata Management:- Only admin can set/update metadata via
MsgSetDenomMetadata
- Metadata stored via bank keeper using
SetDenomMetaData()
- Metadata must pass bank keeper validation
4. Before-Send Hooks
Hook Mechanism:- Custom logic executed before token transfers
- Implemented as CosmWasm contracts
- Two execution modes: tracking and blocking
- Used for monitoring/tracking transfers
- Has gas limit of 500,000 gas
- Errors are suppressed (don’t block transfers)
- Used for blocking/controlling transfers
- Can prevent transfers by returning errors
- No gas limit restrictions
- Only whitelisted contracts can be used as hooks
- Whitelist managed through governance parameters
- Admin can set/remove hooks for their tokens
- Hook validation uses
AssertIsHookWhitelisted()
Security Model
Permission System
Creator Permissions:- Create tokens with their address as admin
- Pay creation fees (if configured)
- Choose subdenom (within length constraints)
- All token management operations
- Can delegate admin to another address
- Can renounce admin (irreversible)
- Update module parameters via
MsgUpdateParams
- Manage hook whitelist
- Set fee collector address
Hook Security
Whitelist Protection:- Only approved contracts can be used as hooks
- Whitelist entries match
CodeID
andDenomCreator
- Prevents malicious hook deployment
- Contract must exist and match whitelist entry
- Creator and hook contract must match whitelist entry
- Hooks are skipped (not blocked) if removed from whitelist
Economic Security
Creation Fees:- Configurable through
denom_creation_fee
parameter - Fees sent to
fee_collector_address
- Both fee and collector must be set together or both unset
- Additional gas cost via
denom_creation_gas_consume
parameter - TrackBeforeSend hooks have 500,000 gas limit
- Gas consumption prevents infinite contract calls
Force Transfer Capability
Admin Override:- Admin can force transfers that bypass before-send hooks via
MsgForceTransfer
- Transfers tokens directly between any two addresses
- Does not trigger hook validation or execution
Implementation Details
State Storage
Authority Metadata:- Maps denomination to admin address
- Stored per-denom for efficient lookup
- Stores contract address for each denomination
- Uses
BeforeSendHookAddressPrefixKey
for storage
- Tracks denoms created per creator address
- Used for
DenomsFromCreator
queries
Length Constraints
Based on SDK’s 128-byte maximum denom length:MaxSubdenomLength = 44
MaxHrpLength = 16
MaxCreatorLength = 75
(59 + 16)