tmpnet

README

tmpnet (temporary network fixture)

This package contains configuration and interfaces that are independent of a given orchestration mechanism (e.g. local). The intent is to enable tests to be written against the interfaces defined in this package and for implementation-specific details of test network orchestration to be limited to test setup and teardown.

What's in a name?

The name of this package was originally testnet and its cli was testnetctl. This name was chosen in ignorance that testnet commonly refers to a persistent blockchain network used for testing.

To avoid confusion, the name was changed to tmpnet and its cli tmpnetctl. tmpnet is short for temporary network since the networks it deploys are likely to live for a limited duration in support of the development and testing of node and its related repositories.

Documentation

Index

• Constants
• Variables
• func DefaultJSONMarshal(v interface{}) ([]byte, error)
• func NewTestGenesis(networkID uint32, xChainBalances XChainBalanceMap, ...) (*genesis.UnparsedConfig, error)
• func WaitForHealthy(ctx context.Context, node Node) error
• type FlagsMap
  • func ReadFlagsMap(path string, description string) (*FlagsMap, error)
  • func (f FlagsMap) GetStringVal(key string) (string, error)
  • func (f FlagsMap) SetDefaults(defaults FlagsMap)
  • func (f FlagsMap) Write(path string, description string) error
• type Network
• type NetworkConfig
  • func (c *NetworkConfig) EnsureGenesis(networkID uint32, validatorIDs []ids.NodeID) error
• type Node
• type NodeConfig
  • func NewNodeConfig() *NodeConfig
  • func (nc *NodeConfig) EnsureBLSSigningKey() error
  • func (nc *NodeConfig) EnsureKeys() error
  • func (nc *NodeConfig) EnsureNodeID() error
  • func (nc *NodeConfig) EnsureStakingKeypair() error
  • func (nc *NodeConfig) SetNetworkingConfigDefaults(httpPort uint16, stakingPort uint16, bootstrapIDs []string, ...)
• type NodeURI
• type XChainBalanceMap

Constants

const (
	DefaultNodeCount      = 2 // Minimum required to ensure connectivity-based health checks will pass
	DefaultFundedKeyCount = 50

	DefaultGasLimit = uint64(100_000_000) // Gas limit is arbitrary

	// Arbitrarily large amount of LUX to fund keys on the X-Chain for testing
	DefaultFundedKeyXChainAmount = 30 * units.MegaLux

	// A short min stake duration enables testing of staking logic.
	DefaultMinStakeDuration = time.Second
)

const (
	DefaultNodeTickerInterval = 50 * time.Millisecond
)

Variables

var (
	// Arbitrarily large amount of LUX (10^12) to fund keys on the C-Chain for testing
	DefaultFundedKeyCChainAmount = new(big.Int).Exp(big.NewInt(10), big.NewInt(30), nil)
)

var ErrNotRunning = errors.New("not running")

Functions

func DefaultJSONMarshal

func DefaultJSONMarshal(v interface{}) ([]byte, error)

Marshal to json with default prefix and indent.

func NewTestGenesis

func NewTestGenesis(
	networkID uint32,
	xChainBalances XChainBalanceMap,
	cChainBalances core.GenesisAlloc,
	validatorIDs []ids.NodeID,
) (*genesis.UnparsedConfig, error)

Create a genesis struct valid for bootstrapping a test network. Note that many of the genesis fields (e.g. reward addresses) are randomly generated or hard-coded.

func WaitForHealthy

func WaitForHealthy(ctx context.Context, node Node) error

WaitForHealthy blocks until Node.IsHealthy returns true or an error (including context timeout) is observed.

Types

type FlagsMap

type FlagsMap map[string]interface{}

Defines a mapping of flag keys to values intended to be supplied to an invocation of an luxd node.

func ReadFlagsMap

func ReadFlagsMap(path string, description string) (*FlagsMap, error)

Utility function simplifying construction of a FlagsMap from a file.

func (FlagsMap) GetStringVal

func (f FlagsMap) GetStringVal(key string) (string, error)

GetStringVal simplifies retrieving a map value as a string.

func (FlagsMap) SetDefaults

func (f FlagsMap) SetDefaults(defaults FlagsMap)

SetDefaults ensures the effectiveness of flag overrides by only setting values supplied in the defaults map that are not already explicitly set.

func (FlagsMap) Write

func (f FlagsMap) Write(path string, description string) error

Write simplifies writing a FlagsMap to the provided path. The description is used in error messages.

type Network

type Network interface {
	GetConfig() NetworkConfig
	GetNodes() []Node
	AddEphemeralNode(w io.Writer, flags FlagsMap) (Node, error)
}

Defines network capabilities supportable regardless of how a network is orchestrated.

type NetworkConfig

type NetworkConfig struct {
	Genesis      *genesis.UnparsedConfig
	CChainConfig FlagsMap
	DefaultFlags FlagsMap
	FundedKeys   []*secp256k1.PrivateKey
}

NetworkConfig defines configuration shared or common to all nodes in a given network.

func (*NetworkConfig) EnsureGenesis

func (c *NetworkConfig) EnsureGenesis(networkID uint32, validatorIDs []ids.NodeID) error

Ensure genesis is generated if not already present.

type Node

type Node interface {
	GetID() ids.NodeID
	GetConfig() NodeConfig
	GetProcessContext() node.NodeProcessContext
	IsHealthy(ctx context.Context) (bool, error)
	Stop() error
}

Defines node capabilities supportable regardless of how a network is orchestrated.

type NodeConfig

type NodeConfig struct {
	NodeID ids.NodeID
	Flags  FlagsMap
}

NodeConfig defines configuration for an luxd node.

func NewNodeConfig

func NewNodeConfig() *NodeConfig

func (*NodeConfig) EnsureBLSSigningKey

func (nc *NodeConfig) EnsureBLSSigningKey() error

Ensures a BLS signing key is generated if not already present.

func (*NodeConfig) EnsureKeys

func (nc *NodeConfig) EnsureKeys() error

Ensures staking and signing keys are generated if not already present and that the node ID (derived from the staking keypair) is set.

func (*NodeConfig) EnsureNodeID

func (nc *NodeConfig) EnsureNodeID() error

Attempt to derive the node ID from the node configuration.

func (*NodeConfig) EnsureStakingKeypair

func (nc *NodeConfig) EnsureStakingKeypair() error

Ensures a staking keypair is generated if not already present.

func (*NodeConfig) SetNetworkingConfigDefaults

func (nc *NodeConfig) SetNetworkingConfigDefaults(
	httpPort uint16,
	stakingPort uint16,
	bootstrapIDs []string,
	bootstrapIPs []string,
)

Convenience method for setting networking flags.

type NodeURI

type NodeURI struct {
	NodeID ids.NodeID
	URI    string
}

NodeURI associates a node ID with its API URI.

type XChainBalanceMap

type XChainBalanceMap map[ids.ShortID]uint64

Helper type to simplify configuring X-Chain genesis balances