Get Started
This section covers Zbox CLI concepts, repository configuration, and installation.
Wallet
A wallet is required to hold the tokens. It comes with private and public keys including a secret mnemonic key.
Allocation
An allocation is storage space on Züs dStorage. It's a contract between the client and multiple blobbers for agreed read/write prices for the agreed duration.
dStorage
It's distributed storage network where all the data files are stored.
To properly build components, you must have a machine setup with the following requirements:
- Linux (Ubuntu Preferred) Version: 20.04 and Above Mac(Apple Silicon or Intel) Version: Big Sur and Above Windows : Before proceeding ,install dependencies from here.
- 4 vCPU, 4 Gb Memory at minimum
- 4 GB of space minimum for zbox build components and storage allocation.
Installing and running the Zbox requires deployment-specific dependencies to be preinstalled
The build essential package is required to build and make the zbox application. It includes the necessary GCC/g++ compilers and other essential critical libraries and utilities.
Run apt update command to update the packages
sudo apt update
Get Build-essential package
sudo apt-get install build-essential
Git is required to retrieve and clone the Zbox repository. Install Git by using the command
sudo apt install git
- 1.Clone the Zbox Repository using the command
git clone https://github.com/0chain/zboxcli.git
2.Navigate into zboxcli directory using
cd zboxcli
3.Use the make install command to compile the source code .
make install
This might take a minute. Here is a sample response of successful make install command:

Configuration for the Züs network by default is stored in
network/config.yaml
file of the zbox github repo which we will copy to a new config.yaml
file in our local system . - 1.Make a new .zcn folder in the home directory of your system using
mkdir $HOME/.zcn
2. Copy config.yaml from network directory in zboxcli repo to
.zcn
directorycp network/config.yaml $HOME/.zcn/config.yaml
3. To verify whether the config.yaml exists and network configuration is stored properly. Check the config.yaml details using the command
nano config.yaml
4. Open the
config.yaml
file located at $HOME/.zcn
path of your system.It should look similar to the file below.---
block_worker: https://demo.zus.network/dns
signature_scheme: bls0chain
min_submit: 50
min_confirmation: 50
confirmation_chain_length: 3
max_txn_query: 5
query_sleep_time: 5
# # OPTIONAL - Uncomment to use/ Add more if you want
# preferred_blobbers:
# - http://one.devnet-0chain.net:31051
# - http://one.devnet-0chain.net:31052
# - http://one.devnet-0chain.net:31053
Zbox connects to the Züs network using the
block_worker
field. These network details are automatically fetched from the blockWorker's network API. Preferred Blobbers are also present which you can uncomment for using specified storage providers for handling your files.Start the Zbox by navigating back to the zboxcli directory using
cd zboxcli
and type
./zbox
On a successful run you will see a help section:

The section assumes you have successfully build zbox. zbox provides a long list of components to use. Let's begin with the allocation of storage space on the 0Chain decentralized network.
For creating a storage allocation using Zbox. You need to have a wallet with tokens available for performing allocations.
1. Register a wallet on Zbox to be used both by the blockchain and blobbers. Use the following Zbox command
./zbox register
Successful Response:

By default, the wallet information will be stored in
wallet.json
located in the .zcn folder of the linux home directory.- 2.Get the test tokens into your wallet using the zwallet CLI tool. If you have not installed zwallet CLI clone the repository and install using these commands
git clone https://github.com/0chain/zwalletcli.git
cd zwalletcli
make install
After a successful build, running the
./zwallet
command will output a help section.- 3.Now get the tokens into your wallet by using
./zwallet faucet --methodName pour --input "{Pay day}"
On Successful response:

- 4.Check Token balance in zwallet using the
./zwallet getbalance
Response:

- 6.Once the wallet has an available balance, you can create a storage allocation by using the Zbox
newallocation
command. To understand the syntax type
./zbox newallocation --help
This will output the mandatory and optional flags that need to be added with the
newallocation
command.Here are the parameters :Parameter | Description | Default | Valid Values |
---|---|---|---|
allocationFileName | local file to store allocation information | allocation.txt | file path |
cost | returns the cost of the allocation, no allocation created | | flag |
data | number of data shards, effects upload and download speeds | 2 | int |
expire | duration to allocation expiration | 720h | duration |
free_storage | free storage marker file. | | file path |
owner | owner's id, use for funding an allocation for another | | string |
owner_public_key | public key, use for funding an allocation for another | | string |
lock | lock write pool with given number of tokens | | float |
mcct | max challenge completion time | 1h | duration |
parity | number of parity shards, effects availability | 2 | int |
read_price | filter blobbers by read price range | 0-inf | range |
size | size of space reserved on blobbers | 2147483648 | bytes |
usd | give token value in USD | | flag |
write_price | filter blobbers by write price range | 0-inf | range |
7. For getting started we can create a basic allocation with default types. This will only require essential specifiers such as
lock float
. We will add a float value of 0.5
which will lock 0.5 tokens with the allocation. The complete command for creating an allocation would be:./zbox newallocation --lock 0.5
Successful Response will create an allocation with allocation ID:

If you are not able to create allocation and getting errors, check error causes in TIps and Troubleshooting Section.
8. Verify the allocation by using the command.
./zbox listallocations
Last modified 13d ago