initialization

README

initializaion package

Motivation

This package contains all logic necessary for initializing configuration data either for a new chain or a single node via Docker containers.

The motivation for doing this via Docker is to be able to initialize configs of any Merlin version.

For example, while the latest Merlin version is v9, we might want to spin up a chain of v8 and test the upgrade.

Additionally, there are known file permission errors when initializing configurations as non-root. This is troublesome both in CI and locally. Doing this via Docker instead, allows us to initialize these files as a root user, bypassing the file permission issues.

Structure

Each folder in tests/e2e/initialization corresponds to a standalone script. At the time of this writing, we have the following scripts/folders: - chain - for initializing a full chain - node - for initializing a single node

All initialization scripts share a common init.Dockerfile that takes an argument E2E_SCRIPT_NAME. By providing the desired script name to the Dockerfile, we are able to build the image that can run any of these local scripts

Scripts

Initializing a Chain (chain)

From root folder:

make docker-build-e2e-init-chain

This script will build a Docker image that runs a script in the chain package and initializes all configuration files necessary for starting up an e2e chain.

Running The Container

When running a container with the specified script, it must mount a folder on a volume to have all configuration files produced.

Additionally, it takes the following arguments:

• --data-dir
  • the location of where the configuration data is written inside the container (string)
• --chain-id
  • the id of the chain (string)
• --config
  • serialized node configurats (e.g. Pruning and Snapshot options). These correspond to the stuct NodeConfig, located in tests/e2e/initialization/config.go The number of initialized validators on the new chain corresponds to the number of NodeConfigs provided by this parameter
• --voting-period
  • The configurable voting period duration for the chain

initResource, err := m.pool.RunWithOptions(
		&dockertest.RunOptions{
			Name:       chainId,
			Repository: m.ImageConfig.InitRepository,
			Tag:        m.ImageConfig.InitTag,
			NetworkID:  m.network.Network.ID,
			Cmd: []string{
				fmt.Sprintf("--data-dir=%s", mountDir),
				fmt.Sprintf("--chain-id=%s", chainId),
				fmt.Sprintf("--config=%s", validatorConfigBytes),
				fmt.Sprintf("--voting-period=%v", votingPeriodDuration),
				fmt.Sprintf("--expedited-voting-period=%v", expeditedVotingPeriodDuration),
				fmt.Sprintf("--fork-height=%v", forkHeight),
			},
			User: "root:root",
			Mounts: []string{
				fmt.Sprintf("%s:%s", mountDir, mountDir),
			},
		},
		noRestart,
	)

Container Output

Assumming that the container was correctly mounted on a volume, it produces the following:

• mer-test-< chain id >-encode file
  • This is encoded metadata about the newly created chain with its nodes
• mer-test-< chain id > folder
  • For every NodeCondig provided to the container, it will produce a folder with the respective node configs

Example:

$:/tmp/merlin-e2e-testnet-1167397304 $ ls
mer-test-a  mer-test-a-encode

$:/tmp/merlin-e2e-testnet-1167397304/mer-test-a $ cd  mer-test-a

$:/tmp/merlin-e2e-testnet-1167397304/mer-test-a $ ls
mer-test-a-merlin-00  mer-test-a-merlin-11  mer-test-a-merlin-22  mer-test-a-merlin-33

$:/tmp/merlin-e2e-testnet-1167397304/mer-test-a $ cd  mer-test-a-merlin-00

$:/tmp/merlin-e2e-testnet-1167397304/mer-test-a/mer-test-a-merlin-00 $ ls
config  data  keyring-test  wasm

• Here we mounted the container on /tmp/merlin-e2e-testnet-1167397304/mer-testas a volume
• < chain id > = "a"
• 4 NodeConfigs were provided via the --config flag
• mer-test-a-encode output file corresponds to the serialized internalChain struct defined in tests/e2e/initialization/chain.go

Initializing a Node (node)

make docker-build-e2e-init-node

This script will build a Docker image that runs a script in the node package and initializes all data necessary for starting up a new node.

Documentation

Index

• Constants
• Variables
• type Chain
  • func InitChain(id, dataDir string, nodeConfigs []*NodeConfig, ...) (*Chain, error)
• type ChainMeta
• type Node
  • func InitSingleNode(chainId, dataDir string, existingGenesisDir string, nodeConfig *NodeConfig, ...) (*Node, error)
• type NodeConfig

Constants

const (
	// common
	MerDenom            = "umer"
	IonDenom            = "uion"
	StakeDenom          = "stake"
	AtomDenom           = "uatom"
	MerIBCDenom         = "ibc/ED07A3391A112B175915CD8FAF43A2DA8E4790EDE12566649D0C2F97716B8518"
	StakeIBCDenom       = "ibc/C053D637CCA2A2BA030E2C5EE1B28A16F71CCB0E45E8BE52766DC1B241B7787"
	MinGasPrice         = "0.000"
	IbcSendAmount       = 3300000000
	ValidatorWalletName = "val"
	// chainA
	ChainAID      = "mer-test-a"
	MerBalanceA   = 200000000000
	IonBalanceA   = 100000000000
	StakeBalanceA = 110000000000
	StakeAmountA  = 100000000000
	// chainB
	ChainBID      = "mer-test-b"
	MerBalanceB   = 500000000000
	IonBalanceB   = 100000000000
	StakeBalanceB = 440000000000
	StakeAmountB  = 400000000000

	EpochDuration         = time.Second * 60
	TWAPPruningKeepPeriod = EpochDuration / 4
)

Variables

var (
	StakeAmountIntA  = sdk.NewInt(StakeAmountA)
	StakeAmountCoinA = sdk.NewCoin(MerDenom, StakeAmountIntA)
	StakeAmountIntB  = sdk.NewInt(StakeAmountB)
	StakeAmountCoinB = sdk.NewCoin(MerDenom, StakeAmountIntB)

	InitBalanceStrA = fmt.Sprintf("%d%s,%d%s,%d%s", MerBalanceA, MerDenom, StakeBalanceA, StakeDenom, IonBalanceA, IonDenom)
	InitBalanceStrB = fmt.Sprintf("%d%s,%d%s,%d%s", MerBalanceB, MerDenom, StakeBalanceB, StakeDenom, IonBalanceB, IonDenom)
	MerToken        = sdk.NewInt64Coin(MerDenom, IbcSendAmount)   // 3,300umer
	StakeToken      = sdk.NewInt64Coin(StakeDenom, IbcSendAmount) // 3,300ustake

)

Types

type Chain

type Chain struct {
	ChainMeta ChainMeta `json:"chainMeta"`
	Nodes     []*Node   `json:"validators"`
}

func InitChain

func InitChain(id, dataDir string, nodeConfigs []*NodeConfig, votingPeriod, expeditedVotingPeriod time.Duration, forkHeight int) (*Chain, error)

type ChainMeta

type ChainMeta struct {
	DataDir string `json:"dataDir"`
	Id      string `json:"id"`
}

type Node

type Node struct {
	Name          string `json:"name"`
	ConfigDir     string `json:"configDir"`
	Mnemonic      string `json:"mnemonic"`
	PublicAddress string `json:"publicAddress"`
	PublicKey     string `json:"publicKey"`
	PeerId        string `json:"peerId"`
	IsValidator   bool   `json:"isValidator"`
}

func InitSingleNode

func InitSingleNode(chainId, dataDir string, existingGenesisDir string, nodeConfig *NodeConfig, votingPeriod time.Duration, trustHeight int64, trustHash string, stateSyncRPCServers []string, persistentPeers []string) (*Node, error)

type NodeConfig

type NodeConfig struct {
	Name               string // name of the config that will also be assigned to Docke container.
	Pruning            string // default, nothing, everything, or custom
	PruningKeepRecent  string // keep all of the last N states (only used with custom pruning)
	PruningInterval    string // delete old states from every Nth block (only used with custom pruning)
	SnapshotInterval   uint64 // statesync snapshot every Nth block (0 to disable)
	SnapshotKeepRecent uint32 // number of recent snapshots to keep and serve (0 to keep all)
	IsValidator        bool   // flag indicating whether a node should be a validator
}

NodeConfig is a confiuration for the node supplied from the test runner to initialization scripts. It should be backwards compatible with earlier versions. If this struct is updated, the change must be backported to earlier branches that might be used for upgrade testing.