Skip to main content

Getting Started

This document will help you get a kava network up and running locally on your machine. It uses a CLI tool call kvtool that manages the configuration and initial setup of a network. The tool uses docker containers to run a Kava network with some optional configuration.

You must have the following tools:

  1. Go 1.20 - used to build & install kvtool
  2. Docker - used by kvtool to run local networks.

Ensure Go is setup in your PATH​

Once Go & Docker are installed, update your bash_profile to include the go path.

export PATH=/usr/local/go/bin:$PATH
export PATH=$HOME/go/bin:$PATH
export GOPATH=$HOME/go
export GO111MODULE=on

Make sure to source your bash profile or restart it for the changes to take place.

Getting The Kava Repository & Development Tools​

Once you have the core tools installed & set up, its now time to get the following repositories from Github:

  • kava
    • Main Kava Repo that holds all modules
  • kvtool
    • Dev tools to interact with a Kava node

Set Up a Local Blockchain​

Now that you have set up all the tools & repositories in your local machine its finally time to set up a local blockchain.

  • Open a terminal and change into the kvtool directory.
  • Ensure Docker is running.
  • Run make install in your terminal which will install kvtool in your machine.
  • Run kvtool testnet bootstrap. By default, this command will initialize a docker container running the code of the current master branch of kava.

Kava is now running on your local machine! The endpoints are publically exposed to your localhost:

  • RPC: http://localhost:26657
  • REST: http://localhost:1317
  • GRPC: http://localhost:9090
  • GRPC Websocket: http://localhost:9091
  • EVM JSON-RPC: http://localhost:8545
  • EVM Websocket: http://localhost:8546

To interact with the network you can use kava CLI from your local machine by setting the --node flag:

kava --node http://localhost:26657 status

However, it is likely more convenient to run the kava CLI directly in the container. This ensures you are running a compatible version of the CLI and gives you access to the accounts configured in the local chain. To do this, add the following alias:

alias dkava='docker exec -it generated_kavanode_1 kava'

Note that for some architectures or docker versions, the containers are generated with hyphens (-) instead of underscores (_).

This alias execs into the container and runs kava. From there you have access to accounts.

NOTE: Before Kava 9 (v0.16), the kava binary was two separate binaries. One for running the chain (kvd) and a separate one for the cli (kvcli). If running older versions, you will need to use kvcli instead of kava.

Example: Create a new account & fund it:

$ dkava keys add my-test-account

- name: my-test-account
  type: local
  address: kava17fuj33p6y472j3kplsjdz966xlw6cdhwqzl8rl
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AnaP5cFfUDcK4jOGTLPCUPGqtijViYmCAd7XRg7XTQib"}'
  mnemonic: ""


**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.

sign sausage monster group rain kite stage cat brush arm result chalk join hamster cup mass chuckle swing inflict april salmon deposit habit grid

$ dkava tx bank send whale kava17fuj33p6y472j3kplsjdz966xlw6cdhwqzl8rl 1000000000ukava --gas-prices 0.01ukava -y

The above creates a new randomly generated account (kava17fuj33p6y472j3kplsjdz966xlw6cdhwqzl8rl) and funds it from the whale account.

For a list of available accounts see accounts.json, or the keyring directory.

Additionally, you can just exec into a shell in the container. Kvtool manages everything with docker-compose and it exposes a command that will run docker-compose in the required location. The running configuration is in kvtool/full_configs/docker-compose.yaml.

$ kvtool testnet dc -- exec kavanode bash

bash-5.1# kava --help
Daemon and CLI for the Kava blockchain.

Usage:
  kava [command]

Available Commands:
  add-genesis-account Add a genesis account to genesis.json
  assert-invariants   Validates that the input genesis file is valid and invariants pass
  collect-gentxs      Collect genesis txs and output a genesis.json file
  config              Create or query an application CLI configuration file
  debug               Tool for helping with debugging your application
  export              Export state to JSON
  gentx               Generate a genesis tx carrying a self delegation
  help                Help about any command
  init                Initialize private validator, p2p, genesis, and application configuration files
  keys                Manage your application's keys
  migrate             Migrate genesis from v0.17 to v0.18
  query               Querying subcommands
  start               Run the full node
  status              Query remote node for status
  tendermint          Tendermint subcommands
  tx                  Transactions subcommands
  validate-genesis    validates the genesis file at the default location or at the location passed as an arg
  version             Print the application binary version information

Flags:
  -h, --help                help for kava
      --home string         directory for config and data (default "/root/.kava")
      --log_format string   The logging format (json|plain) (default "plain")
      --log_level string    The logging level (trace|debug|info|warn|error|fatal|panic) (default "info")
      --trace               print out full stack trace on errors

Use "kava [command] --help" for more information about a command.

Config Templates​

Config templates control the initial genesis file used to start the network and contain the . They also include all the account keys for accounts configured in the docker container.

The available config templates can be found in config/templates/kava/.

By default, kvtool runs with the master config template which defaults to the master docker tag which is autodeployed whenever a commit is made to the master branch of kava. Occasionally, the configuration may become out of sync with what is currently on the master branch of kava. In these cases, it can be useful to use a template that uses a fixed docker tag with a working configuration:

For example, running a network with v0.21 of kava:

$ kvtool testnet bootstrap --kava.configTemplate v0.21

This won't be subject to changes breaking changes of kava that have yet to be updated in kvtool's master template.

Docker Image Tag​

Additionally, all kava confiug templates support overriding the docker image tag. A full list of available tags is available on Docker Hub.

You can override the tag by setting the KAVA_TAG environment variable. For instance running the master template with a fixed kava version of v0.21.0:

KAVA_TAG=v0.21.0 kvtool testnet bootstrap

Note that at the time you're reading this, the master template's genesis and configuration may not be compatible with kava version v0.21.0.

This is also useful for the development of kava itself. You can build a docker image, give it a tag like kava/kava:TAG_HERE, and then run a local network with the built image. There is a shortcut for this in the kava repo.

cd kava
# the docker-build command builds the docker image and tags it `kava/kava:local`
make docker-build
# then you can run a network with the image you created
KAVA_TAG=local kvtool testnet bootstrap

But wait! There's more!​

kvtool has a lot more functionality than simply running a single local kava network. Be sure to use its --help command and check out the repo's README.md.

It supports things like running two networks with an open IBC channel, chain upgrades, and more.

Be sure to check out our guide on developing for Kava's EVM.

Disclaimer: kvtool is beta software. 😊 Some of its features may not always work as expected. Generally, the commands used in this guide are frequently used enough to be reliable. If you run into any problems, please reach out to us on Discord or by opening an issue.