TX Crust

tx-crust library helps you build and run all the applications needed for development and testing.

Prerequisites

To use tx-crust you need:

• go 1.18 or newer
• gcc
• docker (if you are installing from package manager make sure that docker-buildx is installed. for docker version >23 it must be installed separately. Or you can alternatively follow the official installation guide to install docker-desktop, from this link)

Install them manually before continuing.

Building

1. Clone repos to the directory of your choice (let's call it $TOKENIZEX_PATH):

cd $TOKENIZEX_PATH
git clone https://github.com/tokenize-x/tx-crust
git clone https://github.com/tokenize-x/tx-chain

If you are going to use faucet and explorer, also clone these repos:

git clone https://github.com/tokenize-x/faucet
git clone https://github.com/tokenize-x/callisto

2. Not required but recommended: Add bin directory of all projects to your PATH environment variable:

export PATH="$TOKENIZEX_PATH/tx-crust/bin:$TOKENIZEX_PATH/tx-chain/bin:$TOKENIZEX_PATH/faucet/bin:$TOKENIZEX_PATH/callisto/bin:$PATH"

3. Compile all the required binaries and docker images:

$TOKENIZEX_PATH/tx-chain/bin/tx-chain-builder build images

If you are going to use faucet and explorer, also build their images:

$TOKENIZEX_PATH/faucet/bin/faucet-builder build images
$TOKENIZEX_PATH/callisto/bin/callisto-builder build images

After the command tx-chain-builder build images completes the symbolic links should be created to the tx-crust bin and .cache directory using the following commands.

ln -s $TOKENIZEX_PATH/tx-chain/bin/.cache/txd $TOKENIZEX_PATH/tx-crust/bin/.cache/

ln -s $TOKENIZEX_PATH/tx-chain/bin/txd $TOKENIZEX_PATH/tx-crust/bin/txd

Note: You need to run respective builder build images after you modify that project. For example if you do a modification in tx-chain project, you need to run tx-chain-builder build images.

Executing znet

znet is the tool used to spin up development environment running the same components which are used in production.

znet may be executed using two methods. First is direct where you execute command directly:

$ txcrust znet <command> [flags]

Second one is by entering the znet-environment:

$ txcrust znet [flags]
(<environment-name>) [znet] $ <command>

The second method saves some typing.

Flags

All the flags are optional. Execute

$ txcrust znet <command> --help

to see what the default values are.

--env

Defines name of the environment, it is visible in brackets on the left. Each environment is independent, you may create many of them and work with them in parallel.

--profiles

Defines the list of available application profiles to run. Available profiles:

• 1txd - runs one txd validator (default one)
• 3txd - runs three txd validators
• 5txd - runs five txd validators
• devnet - runs environment similar to our devnet - 3 validators, 1 sentry node, 1 seed node, 2 full nodes
• faucet - runs faucet
• explorer - runs block explorer
• monitoring - runs the monitoring stack
• integration-tests-ibc - runs setup required by IBC integration tests
• integration-tests-modules - runs setup required by modules integration tests

NOTE: 1txd, 3txd, 5txd and devnet are mutually exclusive.

To start fully-featured set you may run:

$ txcrust znet start --profiles=3txd,faucet,explorer,monitoring

NOTE: Notice from here on out, if you already have a znet env started with a set profiles, and you want to start znet with a different set of profiles, you need to remove previous znet env with txcrust znet remove and only then you can start the new env.

--txd-version

The --txd-version allows to start the znet with any previously released version.

$ txcrust znet start --txd-version=v1.0.0 --profiles=3txd,faucet,explorer,monitoring

NOTE: if you already have a znet env started with different profiles, you need to remove it with txcrust znet remove so you can start a new environment.

Also, it's possible to execute tests with any previously released version.

$ txcrust znet test --txd-version=v1.0.0 --test-groups=tx-chain-upgrade

Commands

In the environment some wrapper scripts for znet are generated automatically to make your life easier. Each such <command> calls txcrust znet <command>.

Available commands are:

• start - starts applications
• stop - stops applications
• remove - stops applications and removes all the resources used by the environment
• spec - prints specification of the environment
• tests - run integration tests
• console - starts tmux session containing logs of all the running applications

Example

Basic workflow may look like this:

# Enter the environment:
$ txcrust znet
(znet) [znet] $

# Start applications
(znet) [znet] $ start

# Print spec
(znet) [znet] $ spec

# Stop applications
(znet) [znet] $ stop

# Start applications again
(znet) [znet] $ start

# Stop everything and clean resources
(znet) [znet] $ remove
$

Logs

After entering and starting environment:

$ txcrust znet
(znet) [znet] $ start

it is possible to use logs wrapper to tail logs from an application:

(znet) [znet] $ logs txd-00-val

Playing with the blockchain manually

For each txd instance started by znet wrapper script named after the name of the node is created, so you may call the client manually. There are also three standard keys: alice, bob and charlie added to the keystore of each instance.

If you start znet using default --profiles=1txd there is one txd application called txd-00-val. To use the client you may use txd-00-val wrapper:

(znet) [znet] $ start

Generate a wallet to transfer funds to

(znet) [znet] $ txd-00-val keys add {YOUR_WALLET_NAME}

Take the address the out put of the command above, you will use it in the next commands.

(znet) [znet] $ txd-00-val query bank balances {YOUR_GENERATED_ADDRESS}
(znet) [znet] $ txd-00-val tx bank send bob {YOUR_GENERATED_ADDRESS} 10udevcore
(znet) [znet] $ txd-00-val query bank balances {YOUR_GENERATED_ADDRESS}

Integration tests

You may run integration tests directly:

$ txcrust znet test

Tests run on top of --profiles=integration-tests.

It's also possible to enter the environment first, and run tests from there:

$ txcrust znet
(znet) [znet] $ start --profiles=integration-tests
(znet) [znet] $ tests

# Remember to clean everything
(znet) [znet] $ remove

After tests complete environment is still running so if something went wrong you may inspect it manually.

Hard reset

If you want to manually remove all the data created by znet do this:

• use docker ps -a, docker stop <container-id> and docker rm <container-id> to delete related running containers
• run rm -rf ~/.cache/tx-crust/znet to remove all the files created by znet

Monitoring

If you use the monitoring profile to start the znet you can open http://localhost:3001 to access the Grafana UI (admin/admin credentials). Or use http://localhost:9092 to access the prometheus UI.