Deploy your own OKTC testnet#

This document describes 2 ways to setup a network of oktc nodes, each serving a different usecase:

1. Single-node, local, manual testnet
2. Multi-node, local, automated testnet

Supporting code can be found in the networks directory and additionally the local sub-directories.

Available docker images#

In case you need to use or deploy oktc as a container you could skip the build steps and use the official images, $TAG stands for the version you are interested in:

• docker run -it -v ~/.exchaind:/root/.exchaind okexchain/node:$TAG exchaind init mynode
• docker run -it -p 26657:26657 -p 26656:26656 -v ~/.exchaind:/root/.exchaind okexchain/node:$TAG exchaind start
• ...
• docker run -it -v ~/.exchaind:/root/.exchaind okexchain/node:$TAG exchaincli version

The same images can be used to build your own docker-compose stack.

Single-node, local, manual testnet#

This guide helps you create a single validator node that runs a network locally for testing and other development related uses.

Requirements#

• Install oktc
• Install jq (optional)

Create genesis file and start the network#

# You can run all of these commands from your home directory
cd $HOME

# Initialize the genesis.json file that will help you to bootstrap the network
exchaind init <your_custom_moniker> --chain-id testchain-1

# Create a key to hold your validator account
exchaincli keys add validator

# Add that key into the genesis.app_state.accounts array in the genesis file
# NOTE: this command lets you set the number of coins. Make sure this account has some coins
# with the genesis.app_state.staking.params.bond_denom denom, the default is staking
exchaind add-genesis-account $(exchaincli keys show validator -a) 1000000000okt

# Generate the transaction that creates your validator
exchaind gentx --name validator

# Add the generated bonding transaction to the genesis file
exchaind collect-gentxs

# Now its safe to start `exchaind`
exchaind start --chain-id testchain-1

This setup puts all the data for exchaind in ~/.exchaind. You can examine the genesis file you created at ~/.exchaind/config/genesis.json. With this configuration exchaincli is also ready to use and has an account with tokens (both staking and custom).

Multi-node, local, automated testnet#

From the networks/local directory:

Requirements#

• Install oktc
• Install docker
• Install docker-compose

Build#

Build the exchaind binary (linux) and the okexchain/node docker image required for running the localnet commands. This binary will be mounted into the container and can be updated rebuilding the image, so you only need to build the image once.

# Clone the exchain repo
git clone https://github.com/okx/exchain.git

# Work from the SDK repo
cd exchain

# Build okexchain/node image
make build-docker-exchainnode

Run your testnet#

To start a 4 node testnet run:

make localnet-start

This command creates a 4-node network using the exchaindnode image. The ports for each node are found in this table:

Configuration#

The make localnet-start creates files for a 4-node testnet in ./build by calling the exchaind testnet command. This outputs a handful of files in the ./build directory:

$ tree -L 3 build/
build/
├── gentxs
│   ├── node0.json
│   ├── node1.json
│   ├── node2.json
│   └── node3.json
├── node0
│   ├── exchaincli
│   │   ├── key_seed.json
│   │   └── keyring-test-okexchain
│   └── exchaind
│       ├── config
│       └── data
├── node1
│   ├── exchaincli
│   │   ├── key_seed.json
│   │   └── keyring-test-okexchain
│   └── exchaind
│       ├── config
│       └── data
├── node2
│   ├── exchaincli
│   │   ├── key_seed.json
│   │   └── keyring-test-okexchain
│   └── exchaind
│       ├── config
│       └── data
└── node3
    ├── exchaincli
    │   ├── key_seed.json
    │   └── keyring-test-okexchain
    └── exchaind
        ├── config
        └── data

Each ./build/nodeN directory is mounted to the /exchaind directory in each container.

Logging#

Logs are saved under each ./build/nodeN/exchaind/exchaind.log. You can also watch logs directly via Docker, for example:

docker logs -f exchaindnode0

Keys & accounts#

To interact with exchaincli and start querying state or creating txs, you use the exchaincli directory of any given node as your home, for example:

exchaincli keys list --home ./build/node0/exchaincli

Now that accounts exists, you may create new accounts and send those accounts funds!

NOTE: Each node’s seed is located at ./build/nodeN/exchaincli/key_seed.json and can be restored to the CLI using the exchaincli keys add --restore command

Special binaries#

If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. For example:

# Run with custom binary
BINARY=okchainfoo make localnet-start