network

Documentation

Overview

// Copyright 2021 Evmos Foundation // This file is part of Evmos' Ethermint library. // // The Ethermint library is free software: you can redistribute it and/or modify // it under the terms of the GNU Lesser General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // The Ethermint library is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public License // along with the Ethermint library. If not, see https://github.com/evmos/ethermint/blob/main/LICENSE package network implements and exposes a fully operational in-process Tendermint test network that consists of at least one or potentially many validators. This test network can be used primarily for integration tests or unit test suites.

The test network utilizes SimApp as the ABCI application and uses all the modules defined in the Cosmos SDK. An in-process test network can be configured with any number of validators as well as account funds and even custom genesis state.

When creating a test network, a series of Validator objects are returned. Each Validator object has useful information such as their address and public key. A Validator will also provide its RPC, P2P, and API addresses that can be useful for integration testing. In addition, a Tendermint local RPC client is also provided which can be handy for making direct RPC calls to Tendermint.

Note, due to limitations in concurrency and the design of the RPC layer in Tendermint, only the first Validator object will have an RPC and API client exposed. Due to this exact same limitation, only a single test network can exist at a time. A caller must be certain it calls Cleanup after it no longer needs the network.

A typical testing flow might look like the following:

type IntegrationTestSuite struct {
	suite.Suite

	cfg     testutil.Config
	network *testutil.Network
}

func (s *IntegrationTestSuite) SetupSuite() {
	s.T().Log("setting up integration test suite")

	cfg := testutil.DefaultConfig()
	cfg.NumValidators = 1

	s.cfg = cfg
	s.network = testutil.New(s.T(), cfg)

	_, err := s.network.WaitForHeight(1)
	s.Require().NoError(err)
}

func (s *IntegrationTestSuite) TearDownSuite() {
	s.T().Log("tearing down integration test suite")

	// This is important and must be called to ensure other tests can create
	// a network!
	s.network.Cleanup()
}

func (s *IntegrationTestSuite) TestQueryBalancesRequestHandlerFn() {
	val := s.network.Validators[0]
	baseURL := val.APIAddress

	// Use baseURL to make API HTTP requests or use val.RPCClient to make direct
	// Tendermint RPC calls.
	// ...
}

func TestIntegrationTestSuite(t *testing.T) {
	suite.Run(t, new(IntegrationTestSuite))
}

Copyright 2021 Evmos Foundation This file is part of Evmos' Ethermint library.

The Ethermint library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Ethermint library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Ethermint library. If not, see https://github.com/evmos/ethermint/blob/main/LICENSE

Copyright 2021 Evmos Foundation This file is part of Evmos' Ethermint library.

The Ethermint library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Ethermint library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Ethermint library. If not, see https://github.com/evmos/ethermint/blob/main/LICENSE

Copyright 2021 Evmos Foundation This file is part of Evmos' Ethermint library.

The Ethermint library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Ethermint library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Ethermint library. If not, see https://github.com/evmos/ethermint/blob/main/LICENSE

Index

• func WriteFile(name string, dir string, contents []byte) error
• type AppConstructor
  • func NewAppConstructor(encodingCfg params.EncodingConfig) AppConstructor
• type CLILogger
  • func NewCLILogger(cmd *cobra.Command) CLILogger
  • func (s CLILogger) Log(args ...interface{})
  • func (s CLILogger) Logf(format string, args ...interface{})
• type Config
  • func DefaultConfig() Config
• type Logger
• type Network
  • func New(l Logger, baseDir string, cfg Config) (*Network, error)
  • func (n *Network) Cleanup()
  • func (n *Network) LatestHeight() (int64, error)
  • func (n *Network) WaitForHeight(h int64) (int64, error)
  • func (n *Network) WaitForHeightWithTimeout(h int64, t time.Duration) (int64, error)
  • func (n *Network) WaitForNextBlock() error
• type Validator

Functions

func WriteFile

func WriteFile(name string, dir string, contents []byte) error

Types

type AppConstructor

type AppConstructor = func(val Validator) servertypes.Application

AppConstructor defines a function which accepts a network configuration and creates an ABCI Application to provide to Tendermint.

func NewAppConstructor

func NewAppConstructor(encodingCfg params.EncodingConfig) AppConstructor

NewAppConstructor returns a new simapp AppConstructor

type CLILogger

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

func NewCLILogger

func NewCLILogger(cmd *cobra.Command) CLILogger

func (CLILogger) Log

func (s CLILogger) Log(args ...interface{})

func (CLILogger) Logf

func (s CLILogger) Logf(format string, args ...interface{})

type Config

type Config struct {
	KeyringOptions    []keyring.Option // keyring configuration options
	Codec             codec.Codec
	LegacyAmino       *codec.LegacyAmino // TODO: Remove!
	InterfaceRegistry codectypes.InterfaceRegistry
	TxConfig          client.TxConfig
	AccountRetriever  client.AccountRetriever
	AppConstructor    AppConstructor      // the ABCI application constructor
	GenesisState      simapp.GenesisState // custom gensis state to provide
	TimeoutCommit     time.Duration       // the consensus commitment timeout
	AccountTokens     sdkmath.Int         // the amount of unique validator tokens (e.g. 1000node0)
	StakingTokens     sdkmath.Int         // the amount of tokens each validator has available to stake
	BondedTokens      sdkmath.Int         // the amount of tokens each validator stakes
	NumValidators     int                 // the total number of validators to create and bond
	ChainID           string              // the network chain-id
	BondDenom         string              // the staking bond denomination
	MinGasPrices      string              // the minimum gas prices each validator will accept
	PruningStrategy   string              // the pruning strategy each validator will have
	SigningAlgo       string              // signing algorithm for keys
	RPCAddress        string              // RPC listen address (including port)
	JSONRPCAddress    string              // JSON-RPC listen address (including port)
	APIAddress        string              // REST API listen address (including port)
	GRPCAddress       string              // GRPC server listen address (including port)
	EnableTMLogging   bool                // enable Tendermint logging to STDOUT
	CleanupDir        bool                // remove base temporary directory during cleanup
	PrintMnemonic     bool                // print the mnemonic of first validator as log output for testing
}

Config defines the necessary configuration used to bootstrap and start an in-process local testing network.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a sane default configuration suitable for nearly all testing requirements.

type Logger

type Logger interface {
	Log(args ...interface{})
	Logf(format string, args ...interface{})
}

Logger is a network logger interface that exposes testnet-level Log() methods for an in-process testing network This is not to be confused with logging that may happen at an individual node or validator level

type Network

type Network struct {
	Logger     Logger
	BaseDir    string
	Validators []*Validator

	Config Config
}

Network defines a local in-process testing network using SimApp. It can be configured to start any number of validators, each with its own RPC and API clients. Typically, this test network would be used in client and integration testing where user input is expected.

Note, due to Tendermint constraints in regards to RPC functionality, there may only be one test network running at a time. Thus, any caller must be sure to Cleanup after testing is finished in order to allow other tests to create networks. In addition, only the first validator will have a valid RPC and API server/client.

func New

func New(l Logger, baseDir string, cfg Config) (*Network, error)

New creates a new Network for integration tests or in-process testnets run via the CLI

func (*Network) Cleanup

func (n *Network) Cleanup()

Cleanup removes the root testing (temporary) directory and stops both the Tendermint and API services. It allows other callers to create and start test networks. This method must be called when a test is finished, typically in a defer.

func (*Network) LatestHeight

func (n *Network) LatestHeight() (int64, error)

LatestHeight returns the latest height of the network or an error if the query fails or no validators exist.

func (*Network) WaitForHeight

func (n *Network) WaitForHeight(h int64) (int64, error)

WaitForHeight performs a blocking check where it waits for a block to be committed after a given block. If that height is not reached within a timeout, an error is returned. Regardless, the latest height queried is returned.

func (*Network) WaitForHeightWithTimeout

func (n *Network) WaitForHeightWithTimeout(h int64, t time.Duration) (int64, error)

WaitForHeightWithTimeout is the same as WaitForHeight except the caller can provide a custom timeout.

func (*Network) WaitForNextBlock

func (n *Network) WaitForNextBlock() error

WaitForNextBlock waits for the next block to be committed, returning an error upon failure.

type Validator

type Validator struct {
	AppConfig     *config.Config
	ClientCtx     client.Context
	Ctx           *server.Context
	Dir           string
	NodeID        string
	PubKey        cryptotypes.PubKey
	Moniker       string
	APIAddress    string
	RPCAddress    string
	P2PAddress    string
	Address       sdk.AccAddress
	ValAddress    sdk.ValAddress
	RPCClient     tmclient.Client
	JSONRPCClient *ethclient.Client
	// contains filtered or unexported fields
}

Validator defines an in-process Tendermint validator node. Through this object, a client can make RPC and API calls and interact with any client command or handler.