Quickstart

Quick start using Zbox (pre-config - build - run)

Pre-requisites

Before you start, make sure the following is installed on your machine:

  • Golang (1.21+)

  • Make (the make command)

Clone the repo

You need to clone the zboxcli repo:

git clone https://github.com/0chain/zboxcli.git

This will clone the repo on your local machine in zboxcli in your working directory.

Install dependencies

Move to the zboxcli directory and run the install command

cd zboxcli
make install

This installs the dependencies for the zboxcli tool and then builds the tool binary.

Run the binary

Now the binary is in your zboxcli directory, you can run it like this:

❯ ./zbox
zbox is a decentralized storage application written on the 0Chain platform.
                        Complete documentation is available at https://docs.zus.network/guides/zbox-cli

Usage:
  zbox [command]

Available Commands:
  alloc-cancel        Cancel an allocation
  alloc-fini          Finalize an expired allocation
  bl-info             Get blobber info
  bl-update           Update blobber settings by its delegate_wallet owner
  collect-reward      Collect accrued rewards for a stake pool.
  completion          Generate the autocompletion script for the specified shell
  copy                copy an object(file/folder) to another folder on blobbers
  cp-info             Challenge pool information.
  createdir           Create directory
  decrypt             Decrypt text with passphrase
  delete              delete file from blobbers
  download            download file from blobbers
  feed                download segment files from remote live feed, and upload
  get-download-cost   Get downloading cost
  get-upload-cost     Get uploading cost
  getallocation       Gets the allocation info
  getwallet           Get wallet information
  help                Help about any command
  kill-blobber        punitively deactivate a blobber
  kill-validator      punitively deactivate a validator
  list                list files from blobbers
  list-all            list all files from blobbers
  listallocations     List allocations for the client
  ls-blobbers         Show active blobbers in storage SC.
  ls-validators       Show active Validators.
  meta                get meta data of files from blobbers
  move                move an object(file/folder) to another folder on blobbers
  newallocation       Creates a new allocation
  rename              rename an object(file/folder) on blobbers
  rp-create           Create read pool if missing
  rp-info             Read pool information.
  rp-lock             Lock some tokens in read pool.
  rp-unlock           Unlock some expired tokens in a read pool.
  sc-config           Show storage SC configuration.
  share               share files from blobbers
  shutdown-blobber    deactivate a blobber
  shutdown-validator  deactivate a validator
  sign-data           Sign given data
  sp-info             Stake pool information.
  sp-lock             Lock tokens lacking in stake pool.
  sp-unlock           Unlock tokens in stake pool.
  sp-user-info        Stake pool information for a user.
  start-repair        start repair file to blobbers
  stats               stats for file from blobbers
  transferallocation  Transfer an allocation from one account to another
  update              update file to blobbers
  updateallocation    Updates allocation's expiry and size
  upload              upload file to blobbers
  validator-info      Get validator info
  validator-update    Update validator settings by its delegate_wallet owner
  version             Prints version information
  wp-lock             Lock some tokens in write pool.
  wp-unlock           Unlock some expired tokens in a write pool.

Flags:
      --config string              config file (default is config.yaml)
      --configDir string           configuration directory (default is $HOME/.zcn)
      --fee float                  transaction fee for the given transaction (if unset, it will be set to blockchain min fee)
  -h, --help                       help for zbox
      --network string             network file to overwrite the network details (if required, default is network.yaml)
      --silent                     (default false) Do not show interactive sdk logs (shown by default)
      --wallet string              wallet file (default is wallet.json)
      --wallet_client_id string    wallet client_id
      --wallet_client_key string   wallet client_key
      --withNonce int              nonce that will be used in transaction (default is 0)

Use "zbox [command] --help" for more information about a command.

This output means the tool is installed successfully. It also shows the help text for the tools with the available commands and the global flags (flags applied with any command).

To show the help of any command, run the following:

./zbox <command> --help

Running some basic commands

Let's try two of the simplest commands in zboxcli:

1. Listing blobbers command ls-blobbers

This command lists the information of all the blobbers:

./zbox ls-blobbers

Output:

0chain-core-sdk [INFO]   2024/06/03 19:26:39.990874 wallet_base.go:331: ******* Wallet SDK Version:v1.12.1-3-gbc68f654 ******* (SetLogFile)
0box-sdk        [INFO]   2024/06/03 19:26:39.991473 sdk.go:99: ******* Storage SDK Version: v1.12.1-3-gbc68f654 *******
0chain-core-sdk [INFO]   2024/06/03 19:26:41.506521 transaction_base.go:143: ******* Wallet SDK Version:v1.12.1-3-gbc68f654 ******* (InitZCNSDK)
0box-sdk        [DEBUG]  2024/06/03 19:26:42.597142 networkworker.go:119: Get network result:{"miners":["https://dev2.zus.network/miner01","https://dev3.zus.network/miner01","https://dev1.zus.network/miner01"],"sharders":["https://dev2.zus.network/sharder01","https://dev3.zus.network/sharder01","https://dev1.zus.network/sharder01"]}
- id:                    6f895dfc20b5e55df6b3084eeb69ad604eb232e5853cf054983d7495bdbc9ed7
  url:                   https://dev1.zus.network/blobber02/
  allocated / total capacity: 0 B / 399.7 GiB
  last_health_check:      2024-06-03 19:26:02 +0200 EET
  terms:
    read_price:          0 SAS / GB
    write_price:         10.000 mZCN / GB / time_unit
    max_offer_duration:  0s
- id:                    98f14362f075caf467653044cf046eb9e8a5dfee88dc8b78cad1891748245003
  url:                   https://dev1.zus.network/blobber01/
  allocated / total capacity: 0 B / 399.7 GiB
  last_health_check:      2024-06-03 19:25:59 +0200 EET
  terms:
    read_price:          0 SAS / GB
    write_price:         10.000 mZCN / GB / time_unit
    max_offer_duration:  0s
- id:                    0e2fa9abc5a14231a1e7dc27b129480b732222e8e864d3b4e62d60a8b8ae617b
  url:                   https://dev2.zus.network/blobber02/
  allocated / total capacity: 0 B / 400.7 GiB
  last_health_check:      2024-06-03 19:25:55 +0200 EET
  terms:
    read_price:          0 SAS / GB
    write_price:         10.000 mZCN / GB / time_unit
    max_offer_duration:  0s
- id:                    06166f3dfd72a90cd0b51f4bd7520d4434552fc72880039b1ee1e8fe4b3cd7ea
  url:                   https://dev2.zus.network/blobber01/
  allocated / total capacity: 0 B / 400.7 GiB
  last_health_check:      2024-06-03 19:25:56 +0200 EET
  terms:
    read_price:          0 SAS / GB
    write_price:         10.000 mZCN / GB / time_unit
    max_offer_duration:  0s
- id:                    5c61f8d3e63528dfe45db89a598bd5c42c71b3994f7639d4647268ba75269d9a
  url:                   https://dev3.zus.network/blobber02/
  allocated / total capacity: 0 B / 400.9 GiB
  last_health_check:      2024-06-03 19:25:55 +0200 EET
  terms:
    read_price:          0 SAS / GB
    write_price:         10.000 mZCN / GB / time_unit
    max_offer_duration:  0s
- id:                    8d19a8fd7147279d1dfdadd7e3ceecaf91c63ad940dae78731e7a64b104441a6
  url:                   https://dev3.zus.network/blobber01/
  allocated / total capacity: 0 B / 400.9 GiB
  last_health_check:      2024-06-03 19:25:56 +0200 EET
  terms:
    read_price:          0 SAS / GB
    write_price:         10.000 mZCN / GB / time_unit
    max_offer_duration:  0s

As you can see, the output shows all the blobbers, each with the id, url, allocated capacity, last health check and terms.

2. Listing validators command ls-validators

This command lists all the validators registered in the network

./zbox ls-validators

Output:

0chain-core-sdk [INFO]   2024/06/03 19:30:07.432914 wallet_base.go:331: ******* Wallet SDK Version:v1.12.1-3-gbc68f654 ******* (SetLogFile)
0box-sdk        [INFO]   2024/06/03 19:30:07.433089 sdk.go:99: ******* Storage SDK Version: v1.12.1-3-gbc68f654 *******
0chain-core-sdk [INFO]   2024/06/03 19:30:07.866496 transaction_base.go:143: ******* Wallet SDK Version:v1.12.1-3-gbc68f654 ******* (InitZCNSDK)
0box-sdk        [DEBUG]  2024/06/03 19:30:08.245305 networkworker.go:119: Get network result:{"miners":["https://dev2.zus.network/miner01","https://dev3.zus.network/miner01","https://dev1.zus.network/miner01"],"sharders":["https://dev2.zus.network/sharder01","https://dev3.zus.network/sharder01","https://dev1.zus.network/sharder01"]}
id:                09076967dad6a382456a0ba575ed34b3129482c4bbfb34dc0120429e2761a949
url:               https://dev2.zus.network/validator02/
last_health_check:  2024-06-03 19:29:50 +0200 EET
is killed:         false
is shut down:      false
settings:
  delegate_wallet: fdaa2b74e666a3f609ea714a649d44edd9c46ff468e094b797e1811c533d0b2b
  min_stake:       0 SAS
  max_stake:       0 SAS
  total_stake:     10000000000000
  num_delegates:   50
  service_charge:  10 %
id:                0d4f7b73cea6508669563ff8f181fd3789c7790422fcc851494779af4527c991
url:               https://dev3.zus.network/validator01/
last_health_check:  2024-06-03 19:29:48 +0200 EET
is killed:         false
is shut down:      false
settings:
  delegate_wallet: fdaa2b74e666a3f609ea714a649d44edd9c46ff468e094b797e1811c533d0b2b
  min_stake:       0 SAS
  max_stake:       0 SAS
  total_stake:     10000000000000
  num_delegates:   50
  service_charge:  10 %
id:                2d8cfc6175e5e177f5c547e49c68adf7107ca9a2dc05a05bbe851a9593ed0f34
url:               https://dev1.zus.network/validator01/
last_health_check:  2024-06-03 19:29:54 +0200 EET
is killed:         false
is shut down:      false
settings:
  delegate_wallet: fdaa2b74e666a3f609ea714a649d44edd9c46ff468e094b797e1811c533d0b2b
  min_stake:       0 SAS
  max_stake:       0 SAS
  total_stake:     10000000000000
  num_delegates:   50
  service_charge:  10 %
id:                4ceb15b339632340c25c20db1b8baae39e5ac0d2447bfbb13b0176d1d2acc09a
url:               https://dev3.zus.network/validator02/
last_health_check:  2024-06-03 19:29:50 +0200 EET
is killed:         false
is shut down:      false
settings:
  delegate_wallet: fdaa2b74e666a3f609ea714a649d44edd9c46ff468e094b797e1811c533d0b2b
  min_stake:       0 SAS
  max_stake:       0 SAS
  total_stake:     10000000000000
  num_delegates:   50
  service_charge:  10 %
id:                c949fcbefcaab6a15573e7a56dcb052c4a2cddf69d6484a204cef7d825eebceb
url:               https://dev1.zus.network/validator02/
last_health_check:  2024-06-03 19:29:57 +0200 EET
is killed:         false
is shut down:      false
settings:
  delegate_wallet: fdaa2b74e666a3f609ea714a649d44edd9c46ff468e094b797e1811c533d0b2b
  min_stake:       0 SAS
  max_stake:       0 SAS
  total_stake:     10000000000000
  num_delegates:   50
  service_charge:  10 %
id:                f82ab34a98406b8757f11513361752bab9cb679a5cb130b81a4e86cec50eefc3
url:               https://dev2.zus.network/validator01/
last_health_check:  2024-06-03 19:29:48 +0200 EET
is killed:         false
is shut down:      false
settings:
  delegate_wallet: fdaa2b74e666a3f609ea714a649d44edd9c46ff468e094b797e1811c533d0b2b
  min_stake:       0 SAS
  max_stake:       0 SAS
  total_stake:     10000000000000
  num_delegates:   50
  service_charge:  10 %

As you can see, the output shows all the blobbers, each with the id, url, last health check and settings.

All the commands related to your own data will require a wallet. Use the "Configure your wallet" guide to create or specify a wallet to the command.

Next steps

Here are some useful guides and references for Zboxcli:

PreviousStorage CLINextConfiguring the tool

Last updated