[META] Genesis Management

[zivkovicmilos]

Description

This task proposes the introduction of a top-level genesis tool that is capable of executing operations related to a chain's genesis.json, as outlined in #1189 (library requirements).

It is worth noting that gno currently has a structure for the genesis document, but does not have the tools to fully utilize it:

gno/tm2/pkg/bft/types/genesis.go

Lines 21 to 43 in fa8eb77

	//------------------------------------------------------------
	// core types for a genesis definition
	// NOTE: any changes to the genesis definition should
	// be reflected in the documentation:
	// docs/tendermint-core/using-tendermint.md
	// GenesisValidator is an initial validator.
	type GenesisValidator struct {
	Address Address `json:"address"`
	PubKey crypto.PubKey `json:"pub_key"`
	Power int64 `json:"power"`
	Name string `json:"name"`
	}
	// GenesisDoc defines the initial conditions for a tendermint blockchain, in particular its validator set.
	type GenesisDoc struct {
	GenesisTime time.Time `json:"genesis_time"`
	ChainID string `json:"chain_id"`
	ConsensusParams abci.ConsensusParams `json:"consensus_params,omitempty"`
	Validators []GenesisValidator `json:"validators,omitempty"`
	AppHash []byte `json:"app_hash"`
	AppState interface{} `json:"app_state,omitempty"`
	}

Below, you can find the proposal for the entire suite of subcommands relating to genesis manipulation and creation.

---
title: Genesis command structure
---
flowchart TD
    A(genesis) --> B(generate)
    A --> C(verify)
    A --> D(validator)
    A --> E(balances)
    A --> F(txs)

    D --> D1(add)
    D --> D2(remove)

    E --> E1(add)
    E --> E2(remove)


    F --> F1(add)
    F --> F2(remove)

Loading

generate

The generate subcommand should generate a genesis.json file on disk.

Flags

• --output-path - the output path for the genesis.json. If there is a genesis.json already there, the command fails
• --genesis-time - unix time for the genesis block
• --chain-id - the ID of the chain
• --block-max-tx-bytes - the max size of the block transaction
• --block-max-data-bytes - the max size of the block data
• --block-max-gas - the max gas limit for the block
• --block-time-iota - the block time iota (in ms)

validator

The validator subcommand should manage validators in the genesis.json.

Flags

• --genesis-path - the path to the genesis.json

validator add

The validator add subcommand should add a new validator to the genesis.json. The command should fail if the validator already exists in the genesis.json.

Flags

• --address - the string address of the validator
• --pub-key - the hex representation of the validator's public key
• --name - the name of the validator (must be unique)
• --power - the voting power of the validator

validator remove

The validator remove subcommand should remove a validator from the genesis.json. The command should fail if the validator does not exist in the genesis.json.

Flags

• --address - the string address of the validator

verify

The verify subcommand validates the genesis.json, according to different section rules:

• validates the genesis time is valid
• validates the chain ID is valid
• validates the consensus params for the block are valid
• validates the validator set is valid (and not empty!)
• validates the transactions are valid (format is good)
• validates the balances are valid (format is good)

Flags

• --genesis-path - the path to the genesis.json

balances

The balances subcommand manages the genesis.json balances information.

Flags

• --genesis-path - the path to the genesis.json

balances add

The balances add subcommand adds in the balance information from a specified source (see flags) to the genesis.json.

Flags (EITHER-OR)

• --balance-sheet - the path to the balance file containing addresses in the format <address>=<amount>ugnot
• --single - the direct balance addition in the format <address>=<amount>ugnot
• --parse-export - the path to the tx-archive export containing a list of transactions. The command should parse the exported transactions and calculate balances of initialized accounts

balances remove

The balances remove subcommand removes the balance information of a specific account from the genesis.json.

Flags

• --address - the address of the account whose balance information should be removed from genesis.json

txs

The txs subcommand manages the initial transaction data in the genesis.json.

Flags

• --genesis-path - the path to the genesis.json

txs add

The txs add subcommand imports the transactions from a tx-archive backup to the genesis.json. Existing transactions are skipped.

Flags

• --parse-export - the path to the tx-archive export containing a list of transactions.

txs remove

The txs remove subcommand removes the transaction from the genesis.json. If the transaction doesn't exist, the command fails

Flags

• --hash - the transaction hash (hex format)

PR against branch: feat/genesis

[moul]

Looks great! I recommend reading #1105, even if we don't merge everything. I believe this collection of libraries and tools should be placed in gnosdk/pkg/genesis.