Convex logoCreated with Sketch.

Introduction

Convex Command Line Interface or CLI, allows you to control and setup a local Convex network, or add a peer to an already existing network. The current test Convex network can be found at convex.world.

Overview

This CLI is part of the Convex code base. The CLI has been built to do the following things:

  1. Run a Local Convex network.

  2. Run a Local Peer(s) connected to a local network.

  3. Send and Query transactions within a local network.

  4. Setup accounts within a local network.

  5. Setup key pairs to use for accessing local and remote networks.

  6. Run a Local Peer connected to a remote Convex network.

Getting Started

As yet we have not packaged this in any package manager for downloading so currently the CLI can only be downloaded via Github.

Get the source

You will need to visit convex-dev @ github and clone the repository onto your local computer.

The "develop" branch is currently the latest version.

terminal commands
git clone https://github.com/Convex-Dev/convex.git --branch develop

Convex Projects

The Convex code repository is made up of the following subprojects:

convex-benchmaks

Run benchmarks on the Convex network.

convex-cli

This CLI project.

convex-core

The main Convex core library.

convex-gui

A local Convex network running as a GUI application.

convex-peer

Peer library used to run Convex peers.

Compile and Setup

Once you have downloaded the latest source of Convex, you can now compile the suite of projects.

To do this you need to execute the Maven command:

terminal command
mvn install

or

terminal command
mvn package

If you wish to build without running the tests you can append the option -DskipTests

After building and installing the maven dependencies you should eventually see the following lines generated by the Maven build process:

output
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for convex 0.7.0-SNAPSHOT:
[INFO]
[INFO] convex ............................................. SUCCESS [  0.146 s]
[INFO] convex-core ........................................ SUCCESS [  5.003 s]
[INFO] convex-peer ........................................ SUCCESS [  0.027 s]
[INFO] convex-gui ......................................... SUCCESS [  2.474 s]
[INFO] convex-cli ......................................... SUCCESS [  4.665 s]
[INFO] convex-benchmarks .................................. SUCCESS [  1.644 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  14.463 s
[INFO] Finished at: 0000-00-00T00:00:00+00:00
[INFO] ------------------------------------------------------------------------

Files needed by CLI run a local Network or Peer

The CLI needs 3 types of files before running a local Convex network or as a Peer on any network. The type of files are:

  1. Etch Storage database file. This contains the stored state of the Convex network. Usually, when starting up the initial cluster the first set of peers share the same Etch database. CLI Parameter: --etch

  2. Keystore database file. This file contains the private/public key pairs used for the peers and any subsequent users. CLI Parameters: --keystore, --password

  3. Session file. This is created by the CLI to keep track of the locally running peers, so that if you want to access the local network or add another peer to the local network, the CLI will look at the session file for a randomly available peer to connect to. CLI Parameter: --session

The GUI version and the CLI run the same local network. The only difference is that the GUI stores the genesis keypairs in memory and does not create a session file. This means that some of the CLI features cannot be used with the GUI local network, such as transferring funds, creating accounts.

Running the CLI

Once you have successfully compiled and built Convex projects, you can now run the command line tool.

Mac
./convex help
Linux
./convex help
Windows
convex help

Commands

The CLI is split into command the following commands and subcommands:

Account Commands
Command Sub command Description

account, ac

Manages convex accounts.

balance, bal, ba

Get an account balance.

create, cr

Creates an account on a local network using a public/private key from the keystore.

fund, fu

Transfers funds to an account using a public/private key from the keystore.

information, info, in

Get account information.
Key Commands
Command Sub command Description

key, ke

Manage local Convex key store.

import, im

Import key pairs to the keystore.

generate, ge

Generate one or more key pairs.

list, li

List available key pairs.

export, ex

Export key pair from the keystore.
Local Commands
Command Sub command Description

local, lo

Operates a local convex network.

gui

Starts a local convex test network using the peer manager GUI application.

start, st

Starts a local convex test network, same as GUI but using a command line.
Peer Commands
Command Sub command Description

peer, pe

Operates a local peer.

create, cr

Creates a keypair, new account and a funding stake: to run a local peer.

start, st

Starts a local peer.
Query Command
Command Description

query, qu

Execute a query on the current peer.
Status Command
Command Description

status, st

Reports on the current status of the network.
Transaction Command
Command Description

transaction, transact, tr

Execute a transaction on the network via a peer.
Help Command
Command Description

help

Displays help information about the specified command

Shared Options

There are a few common options that can be used with any command or sub command. They are as follows:

Short Option Long Option Description

-c

--config=<configFilename>

Use the specified config file.

-e

--etch=<etchStoreFilename>

Convex state storage filename. The default is to use a temporary storage filename.

-k

--keystore=<keyStoreFilename>

keystore filename. Default: ~/.convex/keystore.pfx

-p

--password=<password>

Password to read/write to the Keystore

-s

--session=<sessionFilename>

Session filename. Defaults ~/.convex/session.conf

-v

--verbose

Show more verbose log information. You can increase verbosity by using multiple -v or -vvv

-h

--help

Show this help message and exit.

-V

--version

Print version information and exit.

Requesting Help

The CLI supports help using the -h or --help options or the command help. For each sub command, there are more help options.

So for example

terminal command
./convex --help

will show the common options for all commands, and the list of available commands.

terminal command
./convex local start --help

will show the common options as well as the specific options for the convex.local.start command

Starting a local network

The CLI is designed to start a local Convex network. This will allow for the developer/tester to try out Convex in a local environment without effecting any other networks.

Simple local start

The simplest way to start up the local Convex network is to run the following command:

terminal command
./convex local start --password=my-password

In this document, the password option will always be shown as --password=my-password. This is an example of a not very good password to use for storing your keys. We suggest that you use a more secure password instead of my-password.

You will always need to pass the password to the keystore file since the CLI will need access to the keys to create and start up the local peers.

The CLI will automatically create 4 keypairs and place them in the keystore. The CLI will then start up 4 peers all sharing a single temporary local Etch Database in the /tmp folder.

The Simple local start consists of the following steps:

  1. Create the count number of peer keypairs.

  2. Store the new keypairs in the keystore.

  3. Start up the local network using the newly created keys.

Local start with peer keys

While the simple local network start will auto-generate public keys for the local peers and create the peer accounts. You have the option instead to start the local network using a predetermined set of keys from your keystore. To do this you need to provide a list of public keys that you want the CLI to use to start up the local network.

If you have already used the simple local start, you can get the list of keys created by running the List keys, this will show you the list of keys that have been stored in the key store.

terminal session
./convex key list --password=my-password

Index Public Key
1 6e89035fce6d842b65e7831433fb3426928865a3c8de9536cfa50a1928eb0276 (1)
2 13e691e05dee5a2c5ad90f6802f4ac5c274582ca5332516dc4740ae55d817856
3 8291e8976e0ee0363f98f819712552924e1dd1d8ab77c4dc8577765ee3eb2d36
4 ce55bb850cefaf87c5a16ab7c410f942e11463d0000eb71e8a22e6ce76301b5c
5 21076aa0c88baba170e62196b5735316f6cc1c5bfe672c0c1e5f9b85d8aaf8cb
1 First keypair stored in the keystore with the public key starting with 6e89035fce6…​ or at index position #1

See Managing your Keys - The Keystore for more informaton.

To start up the local Convex network with the first 4 public keys for the first 4 peers you can run the following command:

terminal command
./convex local start --public-key=6e89035 --public-key=13e691e --public-key=8291e89 --public-key=ce55bb8 --password=my-password

or you can combine the public key fields together into a single comma seperated list option such as:

terminal command
./convex local start --public-key=6e89035,13e691e,8291e89,ce55bb8 --password=my-password

This will now start up a local Convex network with 4 peers each using a public key from the list provided in the keystore.

To start the same peers using the same public keys you can also use the index number in the keystore. So the line:

./convex local start --index-key=1,2,3,4 --password=my-password

Will start the same set of peers as above using the first 4 key pairs from the keystore.

Local start with port numbers

By default, the CLI start a local network with each peer assigned a random port number. You can specify the port numbers used for each peer, by setting the --ports option.

The --ports option takes a list or range of port numbers.

You can use multiple --ports options such as:

./convex local start --index-key=1,2,3,4 --password=my-password --ports=8081 --ports=8082 --ports=8083 --ports=8084

or you can provide a list of ports to use for each peer:

./convex local start --index-key=1,2,3,4 --password=my-password --ports=8081,8082,8083,8084

or a range of port numbers:

./convex local start --index-key=1,2,3,4 --password=my-password --ports=8081-8084

or an open range for any number of peers:

./convex local start --index-key=1,2,3,4 --password=my-password --ports=8081-

or a combination of the above, where the first peer uses port 8088, and all subsequent peers use ports from 8090:

./convex local start --index-key=1,2,3,4 --password=my-password --ports=8088 --ports=8090-

Local start with config file

You can create a config file and assign the command options as config items. You can then start your local network using a config file, instead of providing a list of keys.

terminal command
./convex local start --config=example_convex_local_start.conf

Config Parameters for convex.local.start

file: example_convex_local_start.conf
    # etch storage database
    convex.etch = (1)

    # default keystore filename
    convex.keystore =$HOME/.convex/keystore.pfx

    # default session filename
    convex.session = $HOME/.convex/session.conf

    # number of peers to start
    convex.local.start = 4

    # comma list of index of keys or items (2)
    convex.local.start.index-key=

    # comma list of public-key hex values, or multiple items
    convex.local.start.public-key=6e89035
    convex.local.start.public-key=13e691e
    convex.local.start.public-key=8291e89
    convex.local.start.public-key=ce55bb8

    convex.local.start.ports=8090- (3)

    # keystore password
    convex.local.password = (4)
1 If no filename is provided, then the CLI will create a temporary etch storage database in the temp folder.
2 You can provide a list of public keys or indexes or duplicate settings with different values. 
convex.local.index-key = 1,2,3
# is the same as
convex.local.index-key = 1
convex.local.index-key = 2
convex.local.index-key = 3
3 The peers will use port 8090 onwards
4 If you do not provide a password, then the CLI will request a password on starting the local network.

Starting a local Peer

How to start a local peer, and join a local Convex network.

To start a local peer you first need to do the following:

  1. Start a local Convex network. see Starting a local network.

  2. Create a keypair, or select an unused keypair to use for the peer.

  3. Create an account for the peer.

  4. Assign funds to the peer account.

  5. Assign the peer account funds for the peer stake.

This type of blockchain technology uses the Convergent Proof of Stake (CPoS) algorithm, where each peer has a public key and a stake amount. The stake amount decides the peers voting control in the CPoS algorithm. See Convex Technology

The following command does all of the above except step #1:

./convex peer create --password=my-password

You will then get back from the peer create command something like this:

Public Peer Key: 0xbc1290834e1953b2952624ab8ce34e87d308ba975d655163f9fe47283f0436aa
Address: 45
Balance: 199945799
Inital stake amount: 9800000000
Peer start line: ./convex peer start --password=my-password --address=45 --public-key=bc1290

you can then copy the Peer start line: and run a peer with the local network.

./convex peer start --password=my-password --address=45 --public-key=bc1290

Setting up a local Peer with Convex.world

To start a local peer connected to the convex.world network you will need to first setup the peer

Peer Setup in convex.world

  • Access the convex.world/sandbox

  • Create a new account, you will need the account number later to start the peer.

  • Then go to the 'Request coins' section and request some more coins for your new account.

  • Using the convex-cli generate a new keypair for your new peer. See Generating keypairs

    ./convex key generate --password=my-password
Index Public Key
0 dfb22da0afda1a123e523ded624f184719a4416e9aac6f6fdedd8518fb09fe3c

The public key address, account number and URL shown in this example will be different values for when you run and paste these commands.

  • Using the generated public key and a set stake amount (e.g. 19999 this number must be less than your current balance), paste the following command into the sandbox command area (remember to use your public key instead):

    (create-peer 0xdfb22da0afda1a123e523ded624f184719a4416e9aac6f6fdedd8518fb09fe3c 199999)

    • The syntax for create-peer is:

      (create-peer <public-key> <stake-amount>)

You must use your generated public key to set-key command, as this will lock you out of the sandbox, since the sandbox no longer has the keypair for this account.

  • Setup the new account to use your new peer key, by running the command in the sandbox:

    (set-key 0xdfb22da0afda1a123e523ded624f184719a4416e9aac6f6fdedd8518fb09fe3c)

    • The syntax for set-key is:

      (set-key <public-key>)

Remember to add the 0x at the front of the key value, when using a public key in the sandbox.

Starting the peer with convex.world

If the peer has been setup correctly on convex.world, so you can now start your peer, using the following example command:

./convex peer start --public-key=dfbb22 --password=my-password --address=<address> --port=80888 --url=<my-ip>:8088 --peer=convex.world:18888

Where:

  • <address> is the account number of your peer.

  • <my-ip> is the public ip address of the running peer.

or for example you can create a config file with the following options set:

convex.peer.start.peer=convex.world:18888
convex.peer.start.public-key=dfb22da0afda1a123e523ded624f184719a4416e9aac6f6fdedd8518fb09fe3c
convex.peer.start.address=47
convex.peer.start.url=206.1.1.1:8181
convex.peer.start.port=8181
convex.password=my-password

  • Run convex only using the config file

    ./convex peer start --config=my-peer.conf

You will need allow the peer port remote access. In our example the peer port is set to 8181, so we have allowed TCP traffic to be forwarded and passed to port 8181.

If you wish to connect to your own remote peer, you can by adding the --peer=<remote peer URL> option. This tells the new peer you are starting where a remote peer is located. Once found the started peer will try and sync with the remote peer.

You will also need to set the --url=<my peer URL> option to specify the remote URL of your running peer, so that other peers can communicate to your peer.

Starting the GUI local network

How to start the gui local network.

To start the local GUI network, you can call the command:

./convex local gui

This starts a local network in GUI mode. At the moment the GUI local network does not publish the keypairs used for the network, so the CLI cannot do the following when the GUI network is running:

  1. Account Fund Request

  2. Account Create

  3. Peer Create

Peer Output

Describes the output fields

Sample output
Starting network Id: 0xefe75ea61ad52b38f4455a88911b7bd851dc080090e1b1cb4ec75d85a44eb92d
#2: Peer:1770c3 URL: localhost:43849 Status: J NS Connections: 1/ 0 Consensus:   0 State:efe75e Belief:46bbe3 Msg: connection
#1: Peer:fa26c5 URL: localhost:41635 Status: J NS Connections: 1/ 0 Consensus:   0 State:efe75e Belief:7c7542 Msg: connection
#3: Peer:556deb URL: localhost:37985 Status: J NS Connections: 1/ 0 Consensus:   0 State:efe75e Belief:a43082 Msg: connection
#4: Peer:0fce50 URL: localhost:46559 Status: J NS Connections: 1/ 0 Consensus:   0 State:efe75e Belief:a98ea8 Msg: connection

then later

Sample output
#2: Peer:1770c3 URL: localhost:43849 Status: J  S Connections: 3/ 3 Consensus:  20 State:cfa8fe Belief:2c6f2a Msg: trusted connection
#4: Peer:0fce50 URL: localhost:46559 Status: J  S Connections: 3/ 2 Consensus:  20 State:cfa8fe Belief:2c6f2a Msg: connection
#3: Peer:556deb URL: localhost:37985 Status: J  S Connections: 3/ 3 Consensus:  20 State:cfa8fe Belief:2c6f2a Msg: trusted connection
#4: Peer:0fce50 URL: localhost:46559 Status: J  S Connections: 3/ 3 Consensus:  20 State:cfa8fe Belief:2c6f2a Msg: trusted connection

On every event that occurs for a peer in the cluster, on its own an event is shown as a line.

The event data can be split up into the following fields:

Name Description Example

Index

Peer index starting at 1 within the cluster of peers

#4

Peer

First 6 characters of the public key of the peer

Peer:0fce50

URL

URL of the peer

URL: localhost:46559

Status
NJ

Not Joined
J

Joined
NS

Not Synced
S

Synced

Status: J S

Connections

Peer connection count / Peer trusted connection count

Connections: 3/ 2

Consensus

Consensus level

Consensus: 20

State

First 6 characters of the State hash

State:cfa8fe

Belief

First 6 characters of the Belief hash

Belief:2c6f2a

Msg

Short message of the event that occured on this peer

Msg: trusted connection

Managing your Keys - The Keystore

How to manage the local public/private key pairs.

When using any of the key sub commands, you do not need to be connected to any network.

The option --keystore can be used with any sub command to specify which keystore to use.

Generating keypairs

How to generate a new set of public/private keys.

You need to generate keypairs when:

  1. Creating an account

  2. Creating a new peer

This command allows you to create 1+ keypairs in the keystore.

So for example this will create 10 keypairs:

./convex key generate 10 --password=my-password

List keys

How to list the keys store in the keystore.

To list out your keystore and view the public keys of each keypair.

./convex key list --password=my-password

Exporting keys

How to export the keys from your keystore to encrypted text.

You can export a keypair from the keystore to an encrypted PEM formated text. This is useful if you need to give another user or application access to your network.

You need to provide an --export-password option with the password of the encrypted PEM formated text.

You also need to provide the location of the keypair you wish to export, this can be done using the --index-key or --public-key option.

In this example first list out the keys from the keystore.

./convex key list --password=my-password
1 e7fdcb0bfdfb786b51eedf33b575....
2 373d2a583695ff367dd986e12785....
..

If we now want to export the key #2, then we can use the following command:

./convex key export --index-key=2 --export-password=my-password --password=my-password

or a more reliable way is to use the first hex of the public key

./convex key export --public-key=373d2a583695ff --export-password=my-password --password=my-password

In this example, we have used an insecure password of my-password to encrypt the exported key. We suggest that you use a better password when exporting your keys, and keep the exported PEM formated text secure.

Importing keys

How to import keys into the keystore.

You would need to import keys, when you want to run a peer or send a transaction for an account on another network.

To import a keypair you need to set the options --import-file or --import-file and --import-password.

So for example:

./convex key import --import-file=my_key.pem --import-password=my-password --password=my-password

If the import password is successful, this will import the keypair into the keystore, and show the public key of the imported keypair.

Managing Accounts

Information on how to create, fund and get information about the local accounts.

This set of sub commands manage accounts on the local network. You need to have a local network running on the same computer for these commands to work.

The reason is that the keystore needs to contain the keys for the first genesis accounts in the network. With access to the genesis keypair, the account commands can create an account, and transfer sufficient funds to the new account.

Create an account

How to create a local account.

To create a new account and new keypair, you can just run:

./convex account create --password=my-password

If you wish to use an already defined keypair in your keystore, you can set the --index-key or --public-key options.

./convex account create --public-key=eb1234 --password=my-password

The command returns the account address and public key used to create the account.

Get an accounts balance

How to get an account’s balance.

To obtain the balance of an account, you just need to provide the address of the account.

So to run:

./convex account balance 45

Returns the balance for account #45

Request funds for an account

How to request funds for an account.

With this command, you can request funds for an account. This command transfers the funds from the first peer account to the named account. If the network has been started by the GUI or another user, you will not be able to run this command since the transfer of funds will need to know the private key of the first peer.

For example, first create an account:

./convex account create --password=my-password
Public Key: 1a47522ec91db1209839cf96c99948e77c489310799b29e6bf02038bc67a111c
Address: 46
Account usage: to use this key can use the options --address=46 --public-key=1a4752

You can then request funds for this account by providing the --address and --public-key

./convex account fund --address=46 --public-key=1a4752 --password=my-password
Balance: 100000000

Get information about an account

How to get information about an account.

This command returns the information about the account.

./convex account info 46
Result: {:sequence 0,:balance 100000000,:allowance 0,:environment nil,:metadata nil,:holdings {},:controller nil,:key 0x1a47522ec91db1209839cf96c99948e77c489310799b29e6bf02038bc67a111c}
Data type: Record

Status

How to get the local network status.

This command gets the current status from the local network.

For example:

./convex  status --password=my-password
State hash: 0x68b40285d8b3d5831d829f45acaa5066a793ac1aaa3fb603a07ef8c00512f414 (1)
Timestamp: 1580602820020 (2)
Timestamp value: 2020-02-02T00:20:20.020Z (3)
Global Fees: 0 (4)
Juice Price: 2 (5)
Total Funds: 1,000,000,000,000,000,000 (6)
Number of accounts: 46 (7)
Number of peers: 4 (8)
1 The current hash state for the local peer.
2 The peer’s timestamp as a long number.
3 The Peer’s timestamp
4 The amount of global fees.
5 The current juice price for each transaction.
6 Total funds available in this network.
7 Total number of accounts in this network.
8 Number of peers connected to this network.

Queries

How to execute queries on a local Convex network.

When you run a query, you usually need to provide an account address --address, but this command uses a default account address.

So to find out the current balance using the balance command you can run the following:

./convex query '*balance*'
Result: 260397600000000000
Data type: Long

Transactions

How to execute transactions on a local Convex network.

Submitting a transaction on the Convex network can change the network state, and so this will incur a small fee that is passed back to the peers.

So when sending a transaction you will need to provide a --public-key or --index-key field for the keypair stored in the keystore, and also the correct --address.

For example:

./convex transaction --address=46 --public-key=1cf32e --password=secret "(map inc [1 2 3 4 5])"
The CLI uses the internal Peer API for queries and transactions. To use other Convex networks or remote Convex networks we suggest you use the public Convex Clients instead.