Skip to main content

Avalanche Network Runner

The Avalanche Network Runner allows a user to define, create and interact with a network of Avalanche nodes. It can be used for development and testing.

Note that this tool is not for running production nodes, and that because it is being heavily developed right now, documentation might differ slightly from the actual code.

Installation​

The Avalanche Network Runner repository is hosted at https://github.com/ava-labs/avalanche-network-runner.

That repository's README details the tool.

Clone the repository with:

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

Unless otherwise specified, file paths given below are relative to the root of this repository.

Usage​

The basic pattern for using the Avalanche Network Runner is:

  • Define the network
  • Start the network
  • Interact with it
  • Shutdown

The api package contains client code that allows the user to make API calls to Avalanche nodes within the network.

Please find examples of usage in the examples subdirectory.

Run an Example​

An example can be found at examples/local/fivenodenetwork/main.go. It creates a network of 5 nodes, waits for the nodes to become healthy and then waits for the user to terminate the program with a SIGINT (CTRL + C) or SIGTERM.

To run this example, do:

go run examples/local/fivenodenetwork/main.go

Using Avalanche Network as a Library​

The Avalanche Network Runner is meant to be imported into your programs so that you can use it to programatically start, interact with and stop Avalanche networks. For an example of using the Network Runner in a program, see the code in the example above.

Creating a network is as simple as:

network, err := local.NewDefaultNetwork(log, binaryPath)

where log is a logger of type logging.Logger and binaryPath is the path of the AvalancheGo binary that each node that exists on network startup will run.

For example, the below snippet creates a new network using default configurations, and each node in the network runs the binaries at /home/user/go/src/github.com/ava-labs/avalanchego/build:

network, err := local.NewDefaultNetwork(log,"/home/user/go/src/github.com/ava-labs/avalanchego/build")

Once you create a network, you must eventually call Stop() on it to make sure all of the nodes in the network stop. Calling this method kills all of the Avalanche nodes in the network. You probably want to call this method in a defer statement to make sure it runs.

To wait until the network is ready to use, use the network's Healthy method. It returns a channel which will be notified when all nodes are healthy.

Each node has a unique name. Use the network's GetNodeNames() method to get the names of all nodes.

Use the network's method GetNode(string) to get a node by its name. For example:

names, _ := network.GetNodeNames()
node, _ := network.GetNode(names[0])

Then you can make API calls to the node:

id, _ := node.GetAPIClient().InfoAPI().GetNodeID() // Gets the node's node ID
balance, _ := node.GetAPIClient().XChainAPI().GetBalance(address,assetID,false) // Pretend these arguments are defined

After a network has been created and is healthy, you can add or remove nodes to/from the network:

newNode, _ := network.AddNode(nodeConfig)
err := network.RemoveNode(names[0])

Where nodeConfig is a struct which contains information about the new node to be created. For a local node, the most important elements are its name, its binary path and its identity, given by a TLS key/cert.

You can create a network where nodes are running different binaries -- just provide different binary paths to each:

  stakingCert, stakingKey, err := staking.NewCertAndKeyBytes()
  if err != nil {
   return err
  }
  nodeConfig := node.Config{
    Name: "New Node",
    ImplSpecificConfig: local.NodeConfig{
      BinaryPath: "/tmp/my-avalanchego/build",
    },
    StakingKey:  stakingKey,
    StakingCert: stakingCert,
  }

After adding a node, you may want to call the network's Healthy method again and wait until the new node is healthy before making API calls to it.

Creating Custom Networks​

To create custom networks, pass a custom config (the second parameter) to the local.NewNetwork(logging.Logger, network.Config) function. The config defines the number of nodes when the network starts, the genesis state of the network, and the configs for each node.

Please refer to NetworkConfig for more details.