Avalanche Network Runner

Note

This tool is under heavy development and the documentation/code snippers below may vary slightly from the actual code in the repository. Updates to the documentation may happen some time after an update to the codebase. Nonetheless, this README should provide valuable information about using this tool.

Overview

This is a tool to run and interact with an Avalanche network. The nodes that compose the network can run either locally or in a Kubernetes cluster. This tool may be especially useful for development and testing.

The network you run can be:

Locally: each node runs in a process on your computer.
In Kubernetes: each node runs in a Kubernetes pod. The Kubernetes pods may be on your computer or remote.

Configuration

When the user creates a network, they specify the configurations of the nodes that are in the network upon creation.

A node config is defined by this struct:

type Config struct {
	// Configuration specific to a particular implementation of a node.
	ImplSpecificConfig interface{}
	// A node's name must be unique from all other nodes
	// in a network. If Name is the empty string, a
	// unique name is assigned on node creation.
	Name string
	// True if other nodes should use this node
	// as a bootstrap beacon.
	IsBeacon bool
	// Must not be nil
	StakingKey []byte
	// Must not be nil
	StakingCert []byte
	// May be nil.
	ConfigFile []byte
	// May be nil.
	CChainConfigFile []byte
}

As you can see, some fields of the config must be set, while others will be auto-generated if not provided. Bootstrap IPs/ IDs will be overwritten even if provided.

A node's configuration may include fields that are specific to the type of network runner being used (see ImplSpecificConfig in the struct above.) For example, a node running in a Kubernetes cluster has a config field that specifies the Docker image that the node runs, whereas a node running locally has a config field that specifies the path of the binary that the node runs.

Genesis Generation

You can create a custom AvalancheGo genesis with function network.NewAvalancheGoGenesis:

// Return a genesis JSON where:
// The nodes in [genesisVdrs] are validators.
// The C-Chain and X-Chain balances are given by
// [cChainBalances] and [xChainBalances].
// Note that many of the genesis fields (i.e. reward addresses)
// are randomly generated or hard-coded.
func NewAvalancheGoGenesis(
	log logging.Logger,
	networkID uint32,
	xChainBalances []AddrAndBalance,
	cChainBalances []AddrAndBalance,
	genesisVdrs []ids.ShortID,
) ([]byte, error)

Later on the genesis contents can be used in network creation.

Network Creation

Each network runner implementation (local/Kubernetes) has a function NewNetwork that returns a new network, parameterized on network.Config:

type Config struct {
	// Configuration specific to a particular implementation of a network.
	ImplSpecificConfig interface{}
	// Must not be nil
	Genesis []byte
	// May have length 0
	// (i.e. network may have no nodes on creation.)
	NodeConfigs []node.Config
	// Log level for the whole network
	LogLevel string
	// Name for the network
	Name string
	// How many nodes in the network.
	// TODO move to k8s package?
	NodeCount int
}

The function that returns a new network may have additional configuration fields.

Default Network Creation

The local network runner implementation includes a helper function NewDefaultNetwork, which returns a network using a pre-defined configuration. This allows users to create a new network without needing to define any configurations.

// NewDefaultNetwork returns a new network using a pre-defined
// network configuration.
// The following addresses are pre-funded:
// X-Chain Address 1:     X-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p
// X-Chain Address 1 Key: PrivateKey-ewoqjP7PxY4yr3iLTpLisriqt94hdyDFNgchSxGGztUrTXtNN
// X-Chain Address 2:     X-custom16045mxr3s2cjycqe2xfluk304xv3ezhkhsvkpr
// X-Chain Address 2 Key: PrivateKey-2fzYBh3bbWemKxQmMfX6DSuL2BFmDSLQWTvma57xwjQjtf8gFq
// P-Chain Address 1:     P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p
// P-Chain Address 1 Key: PrivateKey-ewoqjP7PxY4yr3iLTpLisriqt94hdyDFNgchSxGGztUrTXtNN
// P-Chain Address 2:     P-custom16045mxr3s2cjycqe2xfluk304xv3ezhkhsvkpr
// P-Chain Address 2 Key: PrivateKey-2fzYBh3bbWemKxQmMfX6DSuL2BFmDSLQWTvma57xwjQjtf8gFq
// C-Chain Address:       0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
// C-Chain Address Key:   56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
// The following nodes are validators:
// * NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg
// * NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ
// * NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN
// * NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu
// * NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5
func NewDefaultNetwork(
	log logging.Logger,
	binaryPath string,
) (network.Network, error)

The associated pre-defined configuration is also available to users by calling NewDefaultConfig function.

Network Interaction

The network runner allows users to interact with an AvalancheGo network using the network.Network interface:

// Network is an abstraction of an Avalanche network
type Network interface {
	// Returns a chan that is closed when
	// all the nodes in the network are healthy.
	// If an error is sent on this channel, at least 1
	// node didn't become healthy before the timeout.
	// If an error isn't sent on the channel before it
	// closes, all the nodes are healthy.
	// A stopped network is considered unhealthy.
	// Timeout is given by the context parameter.
	// [ctx] must eventually be cancelled -- if it isn't, a goroutine is leaked.
	Healthy(context.Context) chan error
	// Stop all the nodes.
	// Returns ErrStopped if Stop() was previously called.
	Stop(context.Context) error
	// Start a new node with the given config.
	// Returns ErrStopped if Stop() was previously called.
	AddNode(node.Config) (node.Node, error)
	// Stop the node with this name.
	// Returns ErrStopped if Stop() was previously called.
	RemoveNode(name string) error
	// Return the node with this name.
	// Returns ErrStopped if Stop() was previously called.
	GetNode(name string) (node.Node, error)
	// Returns the names of all nodes in this network.
	// Returns ErrStopped if Stop() was previously called.
	GetNodeNames() ([]string, error)
	// TODO add methods
}

and allows users to interact with a node using the node.Node interface:

// An AvalancheGo node
type Node interface {
    // Return this node's name, which is unique
    // across all the nodes in its network.
    GetName() string
    // Return this node's Avalanche node ID.
    GetNodeID() ids.ShortID
    // Return a client that can be used to make API calls.
    GetAPIClient() api.Client
}

Installation

Download

git clone https://github.com/ava-labs/avalanche-network-runner.git

Run Unit Tests

Inside the directory cloned above:

go test ./...

Run an Example

As an example of how to use the network runner, we've included a main.go that uses the local implementation of the network runner. When run, it:

Creates a local five node Avalanche network and waits for all nodes to become healthy.
Prints the names of the nodes
Prints the node ID of one node
Starts a new node
Removes an existing node

The network runs until the user provides a SIGINT or SIGTERM.

It assumes:

You have the latest AvalancheGo binaries at $GOPATH/src/github.com/ava-labs/avalanchego/build. For instructions on setting up AvalancheGo, see here.
The network runner direcory is at $GOPATH/src/github.com/ava-labs/avalanche-network-runner.

To run the demo:

go run examples/local/indepth/main.go

We've also included another example at examples/local/fivenodenetwork/main.go, which just starts a local five node network, waits for the nodes to become healthy, and then runs until the user provides a SIGINT or SIGTERM.

lebdron/avalanche-network-runner