ava-labs / avalanche-cli Goto Github PK

License: Other

Go 98.07% Shell 1.36% Solidity 0.03% TypeScript 0.41% Dockerfile 0.04% Makefile 0.09%

avalanche-cli's Introduction

Avalanche-CLI

Avalanche CLI is a command line tool that gives developers access to everything Avalanche. This release specializes in helping developers develop and test subnets.

Installation

Compatibility

The tool has been tested on Linux and Mac. Windows is currently not supported.

Instructions

To download a binary for the latest release, run:

curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s

The binary will be installed inside the ~/bin directory.

To add the binary to your path, run

export PATH=~/bin:$PATH

To add it to your path permanently, add an export command to your shell initialization script (ex: .bashrc).

Installing in Custom Location

To download the binary into a specific directory, run:

curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s -- -b <relative directory>

Dev Container & Codespace

To get started easily, we provide a Dev Container specification, that can be used using GitHub Codespace or locally using Docker and VS Code. Dev Containers are a concept that utilizes containerization to create consistent and isolated development environment. You can run them directly on Github by clicking Code, switching to the Codespaces tab and clicking Create codespace on main. Alternatively, you can run them locally with the extensions for VS Code or other code editors.

Quickstart

After installing, launch your own custom subnet:

avalanche subnet create <subnetName>
avalanche subnet deploy <subnetName>

Shut down your local deployment with:

avalanche network stop

Restart your local deployment (from where you left off) with:

avalanche network start

Notable Features

Creation of Subnet-EVM, and custom virtual machine subnet configurations
Precompile integration and configuration
Local deployment of subnets for development and rapid prototyping
Fuji Testnet and Avalanche Mainnet deployment of subnets
Ledger support
Avalanche Package Manager Integration

Modifying your Subnet Deployment

You can provide a global node config to edit the way your local avalanchego nodes perform under the hood. To provide such a config, you need to create an avalanche-cli config file. By default, a config file is read in from $HOME/.avalanche-cli/config.json If none exists, no error will occur. To provide a config from a custom location, run any command with the flag --config <pathToConfig>.

To specify the global node config, provide it as a body for the node-config key. Ex:

{
  "network-peer-list-gossip-frequency":"250ms",
  "network-max-reconnect-delay":"1s",
  "public-ip":"127.0.0.1",
  "health-check-frequency":"2s",
  "api-admin-enabled":true,
  "api-ipcs-enabled":true,
  "index-enabled":true
}

Accessing your local subnet remotely

You may wish to deploy your subnet on a cloud instance and access it remotely. If you'd like to do so, use this as your node config:

{
  "node-config": {
    "http-host": "0.0.0.0"
  }
}

Building Locally

To build Avalanche-CLI, you'll first need to install golang. Follow the instructions here: https://go.dev/doc/install.

Once golang is installed, run:

./scripts/build.sh

The binary will be called ./bin/avalanche.

Docker

To make Avalanche CLI work in a docker container, add this

{
  "ipv6": true,
  "fixed-cidr-v6": "fd00::/80"
}

to /etc/docker/daemon.json on the host, then restart the docker service. This is because ipv6 is used to resolve local bootstrap IPs, and it is not enabled on a docker container by default.

Running End-to-End Tests

To run our suite of end-to-end tests, you'll need to install Node-JS and yarn. You can follow instructions to do that here and here.

To run the tests, execute the following command from the repo's root directory:

./scripts/run.e2e.sh

Snapshots usage for local networks

Network snapshots are used by the CLI in order to keep track of blockchain state, and to improve performance of local deployments.

They are the main way to persist subnets, blockchains, and blockchain operations, among different executions of the tool.

Three different kinds of snapshots are used:

The bootstrap snapshot is provided as the starting network state. It is never modified by CLI usage. Designed for fast deploys. Enables full reset of the blockchain state.
The default snapshot is the main way to keep track of blockchain state. Used by default in the tools. It is initialized from the bootstrap snapshot, and after that is updated from CLI operations.
custom snapshots can be specified by the user, to save and restore particular states. Only changed if explicitly asked to do so.

Local networks

Usage of local networks:

The local network will be started in the background only if it is not already running
If the network is not running, both network start and subnet deploy will start it from the default snapshot. subnet deploy will also do the deploy on the started network.
If the network is running, network start will do nothing, and subnet deploy will use the running one to do the deploy.
The local network will run until calling network stop, network clean, or until machine reboot

Default snapshot

How the CLI commands affect the default snapshot:

First call of network start or subnet deploy will initialize default snapshot from the bootstrap snapshot
Subsequent calls to subnet deploy do not change the snapshot, only the running network
network stop persist the running network into the default snapshot
network clean copy again the bootstrap snapshot into the default snapshot, doing a reset of the state

So typically a user will want to do the deploy she needs, change the blockchain state in a specific way, and after that execute network stop to preserve all the state. In a different session, network start or subnet deploy will recover that state.

Custom snapshots

How the CLI commands affect the custom snapshots:

network stop can be given an optional snapshot name. This will then be used instead of the default one to save the state
network start can be given an optional snapshot name. This will then be used instead of the default one to save the state
subnet deploy will take a running network if it is available, so there is a need to use network start previously to do deploys, if wanting to use custom snapshots
network clean does not change custom snapshots

So typically a user who wants to use a custom snapshot will do the deploy she needs, change the blockchain state in a specific way, and after that execute network stop with --snapshot-name flag to preserve all the state into the desired snapshot. In a different session, network start with --snapshot-name flag will be called to load that specific snapshot, and after that subnet deploy can be used on top of it. Notice that you need to continue giving --snapshot-name flag to those commands if you continue saving/restoring to it, if not, default snapshot will be used.

Snapshots dir

~/.avalanche-cli/snapshot will contain all saved snapshots, which can for example be used to pass work around

Detailed Usage

More detailed information on how to use Avalanche CLI can be found at here.

avalanche-cli's People

Contributors

Stargazers

Watchers

avalanche-cli's Issues

Add Whitelist Command

Fix default start time and duration

Add Validator Join Command

Allow to add a default key for key commands

If the user already has created a key, and a command requires a key name, then the key name could be set as default.

But this makes only sense if there is a single key, otherwise no default should be given and rather have the user be prompted for the key to use.

This ticket is to first decide if this is worthwhile, and if yes, implement it.

Add range print text for number of control keys

When setting the number of control keys in deploy, we should add range parameters in the prompt.

Check that keys are available

We should return an error if you attempt a fuji deploy and no keys are available.

Add list to control key capture flow

The control key flow should have list and delete functions, same as precompile configuration.

Allow users to deploy custom VMs

Print instructions or automatically move binary to plugin dir

When we do a validator join, we should copy the VM to the plugin dir or print instructions to do so.

Hide CustomVM from key list without flag

When we list keys, we should hide the custom VM p-chain address unless a --all-networks flag is passed.

Add tests for editConfig function

editCongigFile in cmd/subnet/join.go needs some unit tests.

Review Fuji Deploy Text

Go over all the command text added in the new epic and make sure it is ready to release.

Merge fujiDeploy into main

First, merge main into fujiDeploy, then merge everything back into main.

All PRs must be merged first. Currently blocked on the next avalanchego release.

Bug: Passing genesis filename instead of genesis bytes

H/T to @felipemadero for finding the issue.

Check that there are no spaces in the keyName passed to key Create

Make sure that key names contain no spaces.

VMs should go to /tmp

Update docs to include fuji deploys

Support multiple Subnet-EVM versions

Move snapshotName to a flag

In network start and network stop, we accept the snapshotName as an argument. We don't use this pattern anywhere else in the codebase. We should convert this to a flag.

Setup a custom TX fee destination

When the CLI creates a subnet config, we should be able to specify what happens to gas fees. This may have rollover effects into the deploy process.

Request:

if I’m running an instance of the Subnet EVM via avalanche-cli and I want to give the fees to validators via allowFeeRecipients —where is the validator(s) EVM chain config located so that I can set the corresponding feeRecipient ?
I would expect the Subnet EVM’s config to be in $HOME/.avalanchego/configs/chains/SUBNETID/config.json but my local machine doesn’t have a $HOME/.avalanchego/chains/ directory. How can I figure out the --chain-config-dir when running avalanche-cli so that I can set feeRecipient in the config? Thanks!

minor nit: you should be expecting the Subnet EVM's config to be in $HOME/.avalanchego/configs/chains/CHAINID/config.json

we have to edit two places. First we add allowFeeRecipients to ~/.avalanche-cli/chainName_genesis.json . Second we add feeRecipient to the EVM chain config for each validator.

Create a path for users to import an existing fuji subnet

Users will need to be able to recover a deployed Fuji subnet on a new CLI instance. If we do a Fuji deploy and then delete our subnet config, how can we get it back?

Subnet needs re-deploy on machine restart

Hi, My issues are

First: I may create a subnet, deploy it, stop it, start it again in the same session. But when I restart my machine, the subnet can not start because the backend controller has not started. As I understand, the backend controller starts only with the command "avalanche subnet deploy". But in this case, the subnet is re-deployed and the private key and rpc urls are different now. So, I cannot continue with my current hardhat config and metamask subnet config. I think this is not much useful because, my local environment must be updated on a daily basis. Am I missing something?

Second: normally I'd like to deploy multiple subnets on my local machine in different Linux VMs. But I can not configure the backend controller endpoint port. When I start one subnet, I cannot deploy another one because of the same port confliction. Is there any way to set the backend controller port?

Fix missing text from prompts

Some of the join prompts are missing text. I think prompts can't handle newline characters.

Create a plan for package management development

Write up a work plan for implementing package management and custom VMs.

Add flags to subnet join

We should be able to run these commands in manual and automatic mode without any prompts. We need to add the flags to do so. We definitely need a --fuji and --mainnet. Then if the user provides either print or (--plugin-dir AND avalanchego-config) we skip the confirmations.

Bump CLI Golang Version

Should be version 18.4

Add Balance to key list

The table generated in key list should have the balances of the addresses.

Use test key as control key

In the Fuji deploy process, we should be able to use our generated keys as control keys.

Add tests for subnet import/export

We might want to wait until after our APM integration.

Add more documentation saying not to use keys in production

Make sure we are very explicit saying that keys in our key module should not be used with real funds in production.

Add entropy to vmid and store in sidecar

We'd like to ensure VMIDs are random, so let's add some entropy and store them in the sidecar so we can retrieve them.

subnet deploy tool doesn't work in container environment

I can successfully launch a local subnet on an Ubuntu 18.04 VM instance using the cli subnet command. However, when I try to containerize my local subnet setup for my development pipeline, the avalanche subnet deploy mysubnet command fails inside the container environment:

./bin/avalanche subnet create mysubnet
✔ SubnetEVM
creating subnet mysubnet
Enter your subnet's ChainId. It can be any positive integer.
✔ ChainId: 42069█
Select a symbol for your subnet's native token
✔ Token symbol: tkn█
✔ Low disk use    / Low Throughput    1.5 mil gas/s (C-Chain's setting)
✔ Airdrop 1 million tokens to the default address (do not use in production)
✔ No
Successfully created genesis
root@bd56dc4e98fd:/go/avalanche-cli# ./bin/avalanche subnet deploy mysubnet
✔ Local Network
Deploying [mysubnet] to Local Network
Backend controller started, pid: 4778, output at: /root/.avalanche-cli/runs/deploy2022-06-24T22:58:54Z/avalanche-cli-backend
Installing avalanchego...
Avalanchego installation successful
VM binary does not exist locally, starting download...
.
VM ready. Trying to boot network...                                                                                                                                                         24-Jun-22
Network has been booted. Wait until healthy. Please be patient, this will take some time...
..................................
..........................................................................................................................................................Error: failed to query network health: the health check failed to complete. The server might be down or have crashed, check the logs! rpc error: code = DeadlineExceeded desc = context deadline exceeded
Usage:
  avalanche subnet deploy [subnetName] [flags]

Flags:
  -h, --help    help for deploy
  -l, --local   deploy to a local network

Global Flags:
      --log-level string   log level for the application (default "ERROR")

My dockerfile is very simple to reproduce:

FROM ubuntu:18.04

RUN apt update -y \
  && apt install -y vim \
                    tmux \
                    curl

WORKDIR /root

# install the subnet cli
RUN curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s

ENV PATH="${PATH}:/root/bin"

I build and run an interactive session like this:

docker build -t subnets .
docker run -it --rm --entrypoint bash --name subnets subnets
./bin/avalanche subnet create mysubnet
./bin/avalanche subnet deploy mysubnet

Fuji Deploy should use same default or edit pattern as create

We should edit fuji deploy, addValidator, and join to use the same pattern as subnet create. You should be able to hit enter every time and end up with something that works with sensible defaults wherever possible.

Support multiple Avalanchego versions

Goal

Support multiple, configurable Avalanchego versions
Support the latest avalanchego version without requiring a CLI update

Command Changes

Deploy Subnet

avalanche subnet deploy <subnetName>

Edits

In the deploy flow, ask Github for the latest avago version, download it if not already available. If github is unavailable, use the latest installed version.
Add a flag --avalanchego-version to manually override the avago version.

Technical Details

We should query github to see what the latest release is (if github isn’t available, we can fall back to the latest installed version)
We should remove our hardcoded avago version constants

Implementation Details

All installed binaries will live in the ~/.avalanche-cli/bin/avalanchego directory. There will further subdirectories for each installed version.

Capture NodeId automatically in validator join

Our current implementation of validator join asks the user to enter their node id manually. We need to either provide them more detailed instructions about how to find that or get it for them automatically. Maybe request the nodes RPC URL instead and query for it.

Update readmes, docs, and command strings to reflect our new multi-deploy functionality

Our new flow is:

avalanche network clean resets the environment
You cannot deploy a subnet multiple times (locally) without resetting the environment
You can deploy multiple different subnets simultaneously and run them in parallel

We need to update our readme, our docs website, and our long command descriptions to reflect this.

Use error types not string comparison, when checking ANR server responses [AV-1749]

Create documentation for how the CLI uses snapshots

We need a doc explaining how each command interacts with the snapshot. The process is pretty confusing and we should document it.

Make the closing print statements nicer for fuji deploys

Add --fuji deploy flag

The avalanche subnet deploy command should accept a --fuji flag to skip the select network prompt. This is a mutually exclusive flag with --local.

uknown command error

I'm following this tutorial: https://docs.avax.network/subnets/create-a-fuji-subnet/#private-key

It directs me to run avalanche-cli create key, but avalanche-cli complains:

$ avalanche-cli create key
Error: unknown command "create" for "avalanche"
Run 'avalanche --help' for usage.

What am I missing?
Thanks for your time