Vega Capsule allows you to create a local instance of the Vega network on your computer. This can be used to experiment with using the protocol, such as to:
- Become familiar with Vega, and run commands and API scripts in a controlled environment
- Try out liquidity strategies locally before using the public testnet
- Practice with the market creation process, to make sure proposals will be accepted for a vote
- Simulate network conditions ahead of putting forward a network configuration change proposal
- Simulate market conditions or price scenarios without being concerned about unexpected user behaviour
In order to use Vega Capsule you will need to install Go and Docker:
- Install Go 1.19 or later locally on your machine. Check you have the correct version installed using the following command:
go version
- Install Docker locally on your machine. Check you have the correct version installed using the following command:
docker version
- Install vegacapsule
- Clone the Vega Capsule repository
git clone [email protected]:vegaprotocol/vegacapsule.git
git config --global url."[email protected]:vegaprotocol".insteadOf "https://github.com/vegaprotocol"
cd vegacapsule
- Build Capsule from source
go install
- Validate Capsule installation
vegacapsule --help
- Start Nomad
- Nomad lets you manage services running locally, including executables and Docker images. It comes built in with the Vega Capsule binaries.
vegacapsule nomad
⚠️ Information: You may need to set theGOBIN
environment variable to start Nomad. If you encounter an error, see the Common Issues for guidance.
- Bootstrap with auto-installed dependencies
-
Bootstrap with auto-install will automatically download the required Vega binaries during the bootstrapping process.
-
Use --install to install the hard coded
latestReleaseTag
of Vega:
vegacapsule network bootstrap --config-path=net_confs/config_frontends.hcl --install
- Use --install-release-tag to install a given version of Vega:
vegacapsule network bootstrap --config-path=net_confs/config_frontends.hcl --install-release-tag vX.Y.Z
⚠️ Information: The example bootstrap commands use a base default network configuration with front ends configured to start. If using the front end dApps you will have to switch the network to point to the local instance of the network with the URLhttp://127.0.0.1:3028/query
.
⚠️ Information: The network configurations directory contains a number of defaults for various use cases, such as Capsule with front end dApps or null-blockchain defined. Find out more about the Configuration fields.
- Check Nomad console is running by opening the Nomad UI in a web browser.
Vega Capsule is highly configurable, allowing for networks to be created as desired. This readme uses a base config to get started quickly with a network and dApps. To find out more see the detailed information on both configurations and templating.
Vega Capsule can bootstrap a network based on predetermined configuration. See the configuration documentation to find out more about how to configure your network.
The installed software comes with a number of defaults that can be used, these are in the network configurations directory.
Capsule is using Go's text/template templating engine extended by useful functions from the Sprig library. See the template documentation to find out more about how to configure your network.
The installed software comes with a number of defaults that can be used, these are in the node set templates directory.
In order to start using Vega Capsule to create assets and markets, you'll need to set up the following: Ethereum smart contracts and a Vega Wallet.
In order for the protocol to authorise function executions, such as deposits and withdrawals, the validators need to be set as signers and the thresholds must be set on the multisig smart contract.
- Set up the multisig smart contract
vegacapsule ethereum multisig init
The command will execute the following procedures:
- Set the signature threshold to 1
- Add the validators as signers to the smart contract
- Remove the contract owner from the signers list
- Set the signature threshold to 667
The information to interact with the vega capsule wallet including validator self-staking is still in progress.
Until this section is complete we would advise checking out the CLI wallet documentation.
All available assets can be listed using the Data Node REST API: $DATA_NODE_URL/assets
.
⚠️ Information: The following commands are only for Ethereum assets.
Variables used in examples:
PUB_KEY
- the Vega Wallet public key to deposit or stake to.
AMOUNT
- the amount to be deposited, staked or minted.
ASSET_SYMBOL
- symbol of the asset to be deposited, staked or minted. It can be found via the Data Node endpoint above.
ETH_ADDR
- Ethereum address for assets to be minted to.
# Deposit asset to specific Vega key
vegacapsule ethereum asset deposit --amount $AMOUNT --asset-symbol $ASSET_SYMBOL --pub-key $PUB_KEY
# Stake asset to specific Vega key
vegacapsule ethereum asset stake --amount $AMOUNT --asset-symbol $ASSET_SYMBOL --pub-key $PUB_KEY
# Mint asset to specific Ethereum address
vegacapsule ethereum asset mint --amount $AMOUNT --asset-symbol $ASSET_SYMBOL --to-addr $ETH_ADDR
Confirm an asset has been deposited by querying the Data Node REST API: $DATA_NODE_URL/parties/$PUB_KEY/accounts
Confirm an asset has been staked by querying the Data Node REST API: $DATA_NODE_URL/parties/$PUB_KEY/stake
You can see all available commands by calling the vegacapsule --help
command.
# Generate the network config files
vegacapsule network generate --home-path=/var/tmp/veganetwork/testnetwork --config-path=net_confs/config.hcl
# Start the network
vegacapsule network start --home-path=/var/tmp/veganetwork/testnetwork
# Stop the network
vegacapsule network stop --home-path=/var/tmp/veganetwork/testnetwork
# Resume the network with previous configuration
vegacapsule network start --home-path=/var/tmp/veganetwork/testnetwork
# Destroy the network
vegacapsule network destroy --home-path=/var/tmp/veganetwork/testnetwork
⚠️ Information: Capsule preserves some files when starting and stopping the network, for example any pre-generated keys, the genesis file, and any node configurations in the network configuration file. In order to start a network with new values in these files, use thevegacapsule network destroy
command.
Vega Capsule captures the logs from the nodes running on the network. These can be used to investigate what is happening on the network. Should there be an issue with Vega Capsule, supply the logs from the time of the incident with the issue raised.
Logs from all jobs are stored by default to $CAPSULE_HOME/logs
. There is a CLI available to access and read them.
- To read all logs per single job:
vegacapsule logs --job-id $JOBID
- To follow all logs per job:
vegacapsule logs --job-id $JOBID --follow
- For more information please check
vegacapsule logs --help
This details commonly seen issues users may face when setting up a Vega Capsule network
When trying to start Nomad with the vegacapsule nomad
command, this error may be presented:
Error: GOBIN environment variable has not been found - please set install-path flag instead
To solve it, set the environment variable with the following command:
export GOBIN="$HOME/go/bin"
When trying to bootstrap the network with the vegacapsule network bootstrap
command, this error may be presented:
Error: failed to start network: failed to start network: failed to start vega network: failed to run node sets: failed to wait for node sets: failed to run testnet-nodeset-xxxxxxx job: starting deadline has been exceeded
To solve it, ensure that you are on the main
branch. This can be checked with the command git branch
.
cd .../vegacapsule
git pull
go run ./cmd/docs -type-names 'config.Config' -tag-name hcl -dir-path ./config -description-path ./cmd/docs/hcl_description.md > config.md
go run ./cmd/docs -type-names "config.NodeConfigTemplateContext,datanode.ConfigTemplateContext,faucet.ConfigTemplateContext,genesis.TemplateContext,tendermint.ConfigTemplateContext,vega.ConfigTemplateContext,visor.ConfigTemplateContext,wallet.ConfigTemplateContext" -dir-path . -description-path ./cmd/docs/template_ctx_description.md > templates.md