Avash
Avash is a temporary shell execution environment used to deploy and test on Avalanche networks. Avalanche nodes deployed locally by Avash are exited when Avash exits.
Avash provides the ability to run Lua scripts, which can execute a sequence of shell commands in Avash. This allows for automation of tasks. For instance, one could create a Lua script to deploy a network of Avalanche nodes where each node has some given configuration. This makes testing easier.

Installation

Requirements

    Golang 1.16.8 or later
    AvalancheGo

Quick Setup

To download and build Avash:
1
git clone https://github.com/ava-labs/avash.git; cd avash; go build
Copied!
To run Avash and fire up a 5 node staking network:
1
./avash
2
Config file set: /Users/username/.avash.yaml
3
Avash successfully configured.
4
avash> runscript scripts/five_node_staking.lua
5
RunScript: Running scripts/five_node_staking.lua
6
RunScript: Successfully ran scripts/five_node_staking.lua:
Copied!

Configuration

While Avash can be started without a premade configuration file, it’s available as an option for tweaking some of the shell’s global settings. Avash will search for .avash.yaml in the $HOME directory by default, but the --config flag can be used to set a custom configuration filepath to look for.
Below is the format of an Avash configuration file:
1
avalancheLocation: <filepath>
2
datadir: <directory>
3
log:
4
terminal: <log-level>
5
logfile: <log-level>
6
dir: <directory>
Copied!
The field arguments are described as follows:
    <filepath> - A full path to a file. Example: /home/username/file.txt
    <directory> - A full path to a directory. Example: /home/username/folder
    <log-level> - A valid log level to filter logged messages. Must be one of: {verbo, debug, info, warn, error, fatal, off}

Fields

avalancheLocation
1
Path to AvalancheGo binary.
2
3
Type:
4
optional, <filepath>
5
6
Default:
7
$GOPATH/src/github.com/ava-labs/avalanchego/build/avalanchego
Copied!
datadir
1
Path to store Avash data at.
2
3
Type:
4
optional, <directory>
5
6
Default:
7
$GOPATH/src/github.com/ava-labs/avash/stash
Copied!
log.terminal
1
Log level for messages logged to terminal.
2
3
Type:
4
optional, <log-level>
5
6
Default:
7
info
Copied!
log.logfile
1
Log level for messages logged to log files.
2
3
Type:
4
optional, <log-level>
5
6
Default:
7
info
Copied!
log.dir
1
Path to put log directory at.
2
3
Type:
4
optional, <directory>
5
6
Default:
7
<datadir>/logs
Copied!

Using Avash

Opening a shell

Start a new instance of Avash with ./avash.
Run help to see the commands available.
Run help [command] to see the list of options available for that command.
Ex:
1
help procmanager
2
help procmanager start
Copied!

Commands

Avash comes with the following root commands:
    avawallet - Tools for interacting with Avalanche Payments over the network.
    callrpc - Issues an RPC call to a node.
    exit - Exits the shell.
    help - Displays help text.
    network - Tools for interfacing with remote hosts.
    procmanager - Interact with the Avash process manager.
    runscript - Runs the provided script.
    setoutput - Sets shell log output.
    startnode - Starts a node.
    varstore - Tools for creating variable stores and printing variables within them.
These can be enumerated or auto-completed using the tab key and are explained in detail below.
avawallet
Warning: This wallet is held in memory and all data is wiped upon exit. This should only be used for testing.
1
Tools for interacting with Avalanche Payments over the network. Using this
2
command we can create, send, and get the status of a transaction.
3
4
Usage:
5
avash avawallet [command] [flags]
6
7
Available Commands:
8
addkey Adds a private key to a wallet.
9
balance Checks the balance of an address from a node.
10
compare Compares the UTXO set between two wallets.
11
create Creates a wallet.
12
maketx Creates a signed transaction.
13
newkey Creates a random private key.
14
refresh Refreshes UTXO set from node.
15
remove Removes a transaction from a wallet's UTXO set.
16
send Sends a transaction to a node.
17
spend Spends a transaction from a wallet's UTXO set.
18
status Checks the status of a transaction on a node.
19
writeutxo Writes the UTXO set to a file.
Copied!
callrpc
1
Issues an RPC call to a node endpoint for the specified method and params.
2
Response is saved to the local varstore.
3
4
Usage:
5
callrpc [node name] [endpoint] [method] [JSON params] [var scope] [var name]
Copied!
exit
1
Exit the shell, attempting to gracefully stop all processes first.
2
3
Usage:
4
avash exit
Copied!
help
1
Help provides help for any command in the application.
2
Simply type avash help [path to command] for full details.
3
4
Usage:
5
avash help [command] [flags]
Copied!
network
1
Tools for interfacing with remote hosts. Using this command we can
2
deploy and remove node networks via SSH and a configuration file.
3
4
Usage:
5
avash network [command] [flags]
6
7
Available Commands:
8
deploy Deploys a remote network of nodes.
9
remove Removes a remote network of nodes.
Copied!
CONFIGURATION
To deploy and remove networks, a .yaml network configuration file is required. An example is provided in the Avash codebase at example.network.yaml and should have the following format:
1
# List of hosts
2
hosts:
3
- user: <SSH-username>
4
ip: <host-IP>
5
# List of nodes
6
nodes:
7
- name: <node-name>
8
# Set of node CLI flags
9
flags:
10
<CLI-flag>: <value>
11
# ...
Copied!
This can be used to simultaneously deploy many nodes on many hosts. A full list of CLI flags can be found here.
procmanager
1
Used to list, stop, and start nodes.
2
3
Usage:
4
avash procmanager [command] [flags]
5
6
Available Commands:
7
kill Kills the process named if currently running.
8
killall Kills all processes if currently running.
9
list Lists the processes currently running.
10
metadata Prints the metadata associated with the node name.
11
remove Removes the process named.
12
start Starts the process named if not currently running.
13
startall Starts all processes if currently stopped.
14
stop Stops the process named if currently running.
15
stopall Stops all processes if currently running.
Copied!
runscript
1
Runs the script provided in the argument, relative to the present working directory.
2
3
Usage:
4
avash runscript [script file] [flags]
Copied!
setoutput
1
Sets the log level of a specific log output type.
2
3
Usage:
4
avash setoutput [log output] [log level]
Copied!
startnode
1
Starts an Avalanche client node using procmanager and gives it a name. Example:
2
3
startnode MyNode1 --public-ip=127.0.0.1 --staking-port=9651 --http-port=9650 ...
4
5
Usage:
6
avash startnode [node name] args... [flags]
Copied!
varstore
1
Tools for creating variable stores and printing variables within them.
2
Using this command we can create variable stores, list all variables they store, and print data placed into these stores.
3
4
Usage:
5
avash varstore [command] [flags]
6
7
Available Commands:
8
create Creates a variable store.
9
list Lists all stores. If store provided, lists all variables in the store.
10
print Prints a variable that is within the store.
11
set Sets a simple variable that within the store.
12
storedump Writes the store to a file.
13
vardump Writes the variable to a file.
Copied!

Writing Scripts

Avash uses gopher-lua to run Lua scripts. Scripts can use hooks to allow the user to write code that invokes the current Avash environment.
The functions available to Lua are:
    avash_call - Takes a string and runs it as an Avash command, returning output
    avash_sleepmicro - Takes an unsigned integer representing microseconds and sleeps for that long
    avash_setvar - Takes a variable scope (string), a variable name (string), and a variable (string) and places it in the variable store. The scope must already have been created.
When writing Lua scripts, the standard Lua functionality is available to automate the execution of series of Avash commands. This allows a developer to automate:
    Local network deployments
    Sending transactions
    Order transaction test cases
    Save the value of UTXO sets and test results to disk
    Compare the values of two nodes UTXO sets
    Track expected results and compare them with real nodes
Example Lua scripts are in the scripts folder.
Last modified 30d ago