genutil

package
v0.52.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Dec 18, 2024 License: Apache-2.0 Imports: 34 Imported by: 3,404

README

x/genutil

Concepts

The genutil package contains a variety of genesis utility functionalities for usage within a blockchain application. Namely:

  • Genesis transactions related (gentx)
  • Commands for collection and creation of gentxs
  • InitChain processing of gentxs
  • Genesis file creation
  • Genesis file validation
  • Genesis file migration
  • CometBFT related initialization
    • Translation of an app genesis to a CometBFT genesis
  • Application state export into a genesis file

Genesis

Genutil contains the data structure that defines an application genesis. An application genesis consist of a consensus genesis (g.e. CometBFT genesis) and application related genesis data.

https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/x/genutil/types/genesis.go#L24-L34

The application genesis can then be translated to the consensus engine to the right format:

https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/x/genutil/types/genesis.go#L126-L136

https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/server/start.go#L397-L407

Client

CLI

The genutil commands are available under the genesis subcommand.

add-genesis-account

Add a genesis account to genesis.json. Learn more here.

collect-gentxs

Collect genesis txs and output a genesis.json file.

simd genesis collect-gentxs

This will create a new genesis.json file that includes data from all the validators (we sometimes call it the "super genesis file" to distinguish it from single-validator genesis files).

gentx

Generate a genesis tx carrying a self delegation.

simd genesis gentx [key_name] [amount] --chain-id [chain-id]

This will create the genesis transaction for your new chain. Here amount should be at least 1000000000stake. If you provide too much or too little, you will encounter an error when starting a node.

migrate

Migrate genesis to a specified target (SDK) version.

simd genesis migrate [target-version]

:::tip The migrate command is extensible and takes a MigrationMap. This map is a mapping of target versions to genesis migrations functions. When not using the default MigrationMap, it is recommended to still call the default MigrationMap corresponding the SDK version of the chain and prepend/append your own genesis migrations. :::

validate-genesis

Validates the genesis file at the default location or at the location passed as an argument.

simd genesis validate-genesis

:::warning Validate genesis only validates if the genesis is valid at the current application binary. For validating a genesis from a previous version of the application, use the migrate command to migrate the genesis to the current version. :::

export

Export state to genesis file.

simd genesis export

Some flags are available to customize the export:

  • --for-zero-height: export the genesis file for a chain with zero height
  • --height [height]: export the genesis file for a chain with a given height

Read the help for more information.

Documentation

Overview

Package genutil contains a variety of genesis utility functionality for usage within a blockchain application. Namely:

  • Genesis transactions related (gentx)
  • Commands for collection and creation of gentxs
  • `InitChain` processing of gentxs
  • Genesis file validation
  • Genesis file migration
  • CometBFT related initialization (Translation of an app genesis to a CometBFT genesis)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddGenesisAccounts added in v0.50.10 

func AddGenesisAccounts(
	cdc codec.Codec,
	addressCodec address.Codec,
	accounts []GenesisAccount,
	appendAcct bool,
	genesisFileURL string,
) error

AddGenesisAccounts adds genesis accounts to the genesis state. Where `cdc` is the client codec, `addressCodec` is the address codec, `accounts` are the genesis accounts to add, `appendAcct` updates the account if already exists, and `genesisFileURL` is the path/url of the current genesis file.

func CollectTxs added in v0.40.0 

func CollectTxs(txJSONDecoder sdk.TxDecoder, moniker, genTxsDir string,
	genesis *types.AppGenesis,
	validator types.MessageValidator, valAddrCodec address.ValidatorAddressCodec, addressCodec address.Codec,
) (appGenTxs []sdk.Tx, persistentPeers string, err error)

CollectTxs processes and validates application's genesis Txs and returns the list of appGenTxs, and persistent peers required to generate genesis.json.

func DeliverGenTxs 

func DeliverGenTxs(
	ctx context.Context, genTxs []json.RawMessage,
	stakingKeeper types.StakingKeeper, deliverTx TxHandler,
	txEncodingConfig client.TxEncodingConfig,
) ([]module.ValidatorUpdate, error)

DeliverGenTxs iterates over all genesis txs, decodes each into a Tx and invokes the provided deliverTxfn with the decoded Tx. It returns the result of the staking module's ApplyAndReturnValidatorSetUpdates. NOTE: This isn't used in server/v2 applications.

func ExportGenesisFile 

func ExportGenesisFile(genesis *types.AppGenesis, genFile string) error

ExportGenesisFile creates and writes the genesis configuration to disk. An error is returned if building or writing the configuration to file fails.

func ExportGenesisFileWithTime 

func ExportGenesisFileWithTime(
	genFile, chainID string, validators []sdk.GenesisValidator, appState json.RawMessage, genTime time.Time,
) error

ExportGenesisFileWithTime creates and writes the genesis configuration to disk. An error is returned if building or writing the configuration to file fails.

func GenAppStateFromConfig 

func GenAppStateFromConfig(cdc codec.JSONCodec, txEncodingConfig client.TxEncodingConfig,
	config *cfg.Config, initCfg types.InitConfig, genesis *types.AppGenesis,
	validator types.MessageValidator, valAddrCodec address.ValidatorAddressCodec, addressCodec address.Codec,
) (appState json.RawMessage, err error)

GenAppStateFromConfig gets the genesis app state from the config

func InitGenesis 

func InitGenesis(
	ctx context.Context, stakingKeeper types.StakingKeeper,
	deliverTx TxHandler, genesisState types.GenesisState,
	txEncodingConfig client.TxEncodingConfig,
) (validatorUpdates []module.ValidatorUpdate, err error)

InitGenesis - initialize accounts and deliver genesis transactions NOTE: It isn't used in server/v2 applications.

func InitializeNodeValidatorFiles 

func InitializeNodeValidatorFiles(config *cfg.Config, keyType string) (
	nodeID string, valPubKey cryptotypes.PubKey, err error,
)

InitializeNodeValidatorFiles creates private validator and p2p configuration files.

func InitializeNodeValidatorFilesFromMnemonic added in v0.40.0 

func InitializeNodeValidatorFilesFromMnemonic(config *cfg.Config, mnemonic, keyType string) (
	nodeID string, valPubKey cryptotypes.PubKey, err error,
)

InitializeNodeValidatorFilesFromMnemonic creates private validator and p2p configuration files using the given mnemonic. If no valid mnemonic is given, a random one will be used instead.

func NewAppModule 

func NewAppModule(
	cdc codec.Codec,
	accountKeeper types.AccountKeeper,
	stakingKeeper types.StakingKeeper,
	deliverTx TxHandler,
	txEncodingConfig client.TxEncodingConfig,
	genTxValidator types.MessageValidator,
) module.AppModule

NewAppModule creates a new AppModule object

func ProvideModule added in v0.47.0 

func ProvideModule(in ModuleInputs) appmodule.AppModule

func SetGenTxsInAppGenesisState 

func SetGenTxsInAppGenesisState(
	cdc codec.JSONCodec, txJSONEncoder sdk.TxEncoder, appGenesisState map[string]json.RawMessage, genTxs []sdk.Tx,
) (map[string]json.RawMessage, error)

SetGenTxsInAppGenesisState - sets the genesis transactions in the app genesis state

func ValidateAccountInGenesis 

func ValidateAccountInGenesis(
	appGenesisState map[string]json.RawMessage, genBalIterator types.GenesisBalancesIterator,
	addr string, coins sdk.Coins, cdc codec.JSONCodec,
) error

ValidateAccountInGenesis checks that the provided account has a sufficient balance in the set of genesis accounts.

Types

type AppModule 

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

AppModule implements an application module for the genutil module.

func (AppModule) ConsensusVersion added in v0.43.0 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements HasConsensusVersion

func (AppModule) DecodeGenesisJSON 

func (am AppModule) DecodeGenesisJSON(data json.RawMessage) ([]json.RawMessage, error)

DecodeGenesisJSON returns the genesis transactions for the genutil module. It is an alternative to InitGenesis and used in server/v2 applications.

func (AppModule) DefaultGenesis 

func (am AppModule) DefaultGenesis() json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the genutil module.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(context.Context) (json.RawMessage, error)

ExportGenesis returns the exported genesis state as raw bytes for the genutil module.

func (AppModule) GenTxValidator 

func (am AppModule) GenTxValidator() types.MessageValidator

GenTxValidator returns the genutil module's genesis transaction validator.

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx context.Context, data json.RawMessage) ([]module.ValidatorUpdate, error)

InitGenesis performs genesis initialization for the genutil module. InitGenesis is skipped in a server/v2 application as DecodeGenesisJSON takes precedence.

func (AppModule) IsAppModule added in v0.47.0 

func (AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType added in v0.47.0 

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) Name 

func (AppModule) Name() string

Name returns the genutil module's name. Deprecated: kept for legacy reasons.

func (AppModule) ValidateGenesis 

func (am AppModule) ValidateGenesis(bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the genutil module.

type GenesisAccount added in v0.50.10 

type GenesisAccount struct {
	// Base
	Address string    `json:"address"`
	Coins   sdk.Coins `json:"coins"`

	// Vesting
	VestingAmt   sdk.Coins `json:"vesting_amt,omitempty"`
	VestingStart int64     `json:"vesting_start,omitempty"`
	VestingEnd   int64     `json:"vesting_end,omitempty"`

	// Module
	ModuleName string `json:"module_name,omitempty"`
}

type ModuleInputs added in v0.50.0 

type ModuleInputs struct {
	depinject.In

	AccountKeeper  types.AccountKeeper
	StakingKeeper  types.StakingKeeper
	Config         client.TxConfig
	Cdc            codec.Codec
	DeliverTx      TxHandler              `optional:"true"` // Only used in server v0 applications
	GenTxValidator types.MessageValidator `optional:"true"`
}

ModuleInputs defines the inputs needed for the genutil module.

type TxHandler 

type TxHandler interface {
	ExecuteGenesisTx([]byte) error
}

TxHandler is an interface that defines how genesis txs are handled.

Source Files

View all Source files

Directories

Path Synopsis
client
cli
migration
v052
Package testutil is a generated GoMock package.
 Package testutil is a generated GoMock package.
v2
v2 contains logic and CLI used for genutil by server/v2 / runtime/v2 applications.
 v2 contains logic and CLI used for genutil by server/v2 / runtime/v2 applications.
cli

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.