tokenfactory

package
v0.0.0-...-bf46863 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2023 License: Apache-2.0 Imports: 19 Imported by: 0

README

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. In the future, more admin capabilities may be added. Admins can choose to share admin privileges with other accounts using the authz module. The ChangeAdmin functionality, allows changing the master admin account, or even setting it to "", meaning no account has admin privileges of the asset.

Messages

CreateDenom

Creates a denom of factory/{creator address}/{subdenom} given the denom creator address and the subdenom. Subdenoms can contain [a-zA-Z0-9./].

message MsgCreateDenom {
  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
  string subdenom = 2 [ (gogoproto.moretags) = "yaml:\"subdenom\"" ];
}

State Modifications:

  • Set DenomMetaData via bank keeper.
  • Set AuthorityMetadata for the given denom to store the admin for the created denom factory/{creator address}/{subdenom}. Admin is automatically set as the Msg sender.
  • Add denom to the CreatorPrefixStore, where a state of denoms created per creator is kept.
Mint

Minting of a specific denom is only allowed for the current admin. Note, the current admin is defaulted to the creator of the denom.

message MsgMint {
  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
  cosmos.base.v1beta1.Coin amount = 2 [
    (gogoproto.moretags) = "yaml:\"amount\"",
    (gogoproto.nullable) = false
  ];
}

State Modifications:

  • Safety check the following
    • Check that the denom minting is created via tokenfactory module
    • Check that the sender of the message is the admin of the denom
  • Mint designated amount of tokens for the denom via bank module
Burn

Burning of a specific denom is only allowed for the current admin. Note, the current admin is defaulted to the creator of the denom.

message MsgBurn {
  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
  cosmos.base.v1beta1.Coin amount = 2 [
    (gogoproto.moretags) = "yaml:\"amount\"",
    (gogoproto.nullable) = false
  ];
}

State Modifications:

  • Safety check the following
    • Check that the denom is created via tokenfactory module
    • Check that the sender of the message is the admin of the denom
  • Burn designated amount of tokens for the denom via bank module
ChangeAdmin

Change the admin of a denom. Note, this is only allowed to be called by the current admin of the denom.

message MsgChangeAdmin {
  string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ];
  string denom = 2 [ (gogoproto.moretags) = "yaml:\"denom\"" ];
  string newAdmin = 3 [ (gogoproto.moretags) = "yaml:\"new_admin\"" ];
}

State Modifications:

  • Check that sender of the message is the admin of denom
  • Modify AuthorityMetadata state entry to change the admin of the denom

Tokenfactory Denom Restrictions

Tokenfactory denoms are of form factory/{creator address}/{subdenom}.

  • The Max Subdenom length is 44 characters
  • The Max Creator length is 75 characters
  • All tokenfactory denoms will begin with factory

Please reference the Appendix for more details on the derivation of these limits.

Examples

To create a new token, use the create-denom command from the tokenfactory module. The following example uses the address sei166vhptur29s3gw5qr6dm30s06gej6pr4n6qc4l from mylocalwallet as the default admin for the new token.

Creating a token

To create a new token we can use the create-denom command.

fbchaind tx tokenfactory create-denom ufoo --from mylocalwallet

Mint a new token

Once a new token is created, it can be minted using the mint command in the tokenfactory module. Note that the complete tokenfactory address, in the format of factory/{creator address}/{subdenom}, must be used to mint the token.

fbchaind tx tokenfactory mint 100000000000factory/sei166vhptur29s3gw5qr6dm30s06gej6pr4n6qc4l/ufoo --from mylocalwallet

Checking Token metadata

To view a token's metadata, use the denom-metadata command in the bank module. The following example queries the metadata for the token factory/sei166vhptur29s3gw5qr6dm30s06gej6pr4n6qc4l/ufoo:

fbchaind query bank denom-metadata --denom factory/sei166vhptur29s3gw5qr6dm30s06gej6pr4n6qc4l/ufoo

Check the tokens created by an account

To see a list of tokens created by a specific account, use the denoms-from-creator command in the tokenfactory module. The following example shows tokens created by the account sei166vhptur29s3gw5qr6dm30s06gej6pr4n6qc4l:

fbchaind query tokenfactory denoms-from-creator sei166vhptur29s3gw5qr6dm30s06gej6pr4n6qc4ls

Appendix: Expectations from the Chain

As mentioned above, the chain's bech32 prefix for addresses can be at most 16 characters long.

This comes from denoms having a 128 byte maximum length, enforced from the SDK, and us setting longest_subdenom to be 44 bytes.

A token factory token's denom is: factory/{creator address}/{subdenom}

Splitting up into sub-components, this has:

  • len(factory) = 7
  • 2 * len("/") = 2
  • len(longest_subdenom)
  • len(creator_address) = len(bech32(longest_addr_length, chain_addr_prefix)).

Longest addr length at the moment is 32 bytes. Due to SDK error correction settings, this means len(bech32(32, chain_addr_prefix)) = len(chain_addr_prefix) + 1 + 58. Adding this all, we have a total length constraint of 128 = 7 + 2 + len(longest_subdenom) + len(longest_chain_addr_prefix) + 1 + 58. Therefore len(longest_subdenom) + len(longest_chain_addr_prefix) = 128 - (7 + 2 + 1 + 58) = 60.

Considerations for how we split these 60 bytes between maxes from longest_subdenom and longest_chain_addr_prefix:

  • Per BIP-0173 the technically longest HRP for a 32 byte address ('data field') is 31 bytes. (Comes from encode(data) = 59 bytes, and max length = 90 bytes)
  • subdenom should be at least 32 bytes so hashes can go into it
  • longer subdenoms are very helpful for creating human readable denoms
  • chain addresses should prefer being smaller. The longest HRP in cosmos to date is 11 bytes. (persistence)

For explicitness, its currently set to len(longest_subdenom) = 44 and len(longest_chain_addr_prefix) = 16.

Please note, if the SDK increases the maximum length of a denom from 128 bytes, these caps should increase.

So please don't make code rely on these max lengths for parsing.

Documentation

Overview

The tokenfactory module allows any account to create a new token with the name `factory/{creator address}/{subdenom}`.

- Mint and burn user denom to and form any account - Create a transfer of their denom between any two accounts - Change the admin. In the future, more admin capabilities may be added.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewProposalHandler 

func NewProposalHandler(k keeper.Keeper) govtypes.Handler

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the capability module.

func NewAppModule 

func NewAppModule(
	keeper keeper.Keeper,
	accountKeeper types.AccountKeeper,
	bankKeeper types.BankKeeper,
) AppModule

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock executes all ABCI BeginBlock logic respective to the tokenfactory module.

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements ConsensusVersion.

func (AppModule) EndBlock 

func (am AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock executes all ABCI EndBlock logic respective to the tokenfactory module. It returns no validator updates.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the x/tokenfactory module's exported genesis state as raw JSON bytes.

func (AppModule) GenerateGenesisState 

func (am AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the tokenfactory module.

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the x/tokenfactory module's genesis initialization. It returns no validator updates.

func (AppModule) LegacyQuerierHandler 

func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns the x/tokenfactory module's Querier.

func (AppModule) Name 

func (am AppModule) Name() string

Name returns the x/tokenfactory module's name.

func (AppModule) ProposalContents 

func (am AppModule) ProposalContents(simState module.SimulationState) []simtypes.WeightedProposalContent

ProposalContents doesn't return any content functions for governance proposals.

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

QuerierRoute returns the x/tokenfactory module's query routing key.

func (AppModule) RandomizedParams 

func (am AppModule) RandomizedParams(r *rand.Rand) []simtypes.ParamChange

RandomizedParams creates randomized txfees param changes for the simulator.

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the x/tokenfactory module's invariants.

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) RegisterStoreDecoder 

func (am AppModule) RegisterStoreDecoder(sdr sdk.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder for tokenfactory module's types

func (AppModule) Route 

func (am AppModule) Route() sdk.Route

Route returns the x/tokenfactory module's message routing key.

func (AppModule) WeightedOperations 

func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation

WeightedOperations returns simulator module operations with their respective weights.

type AppModuleBasic 

type AppModuleBasic struct{}

AppModuleBasic implements the AppModuleBasic interface for the capability module.

func NewAppModuleBasic 

func NewAppModuleBasic() AppModuleBasic

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns the x/tokenfactory module's default genesis state.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the x/tokenfactory module's root query command.

func (AppModuleBasic) GetTxCmd 

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the x/tokenfactory module's root tx command.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the x/tokenfactory module's name.

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces 

func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterRESTRoutes 

func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, _ client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the x/tokenfactory module.

Source Files

View all Source files

Directories

Path Synopsis
client
cli
wasm
#nosec G101
 #nosec G101

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.