Zbox CLI

0CHAIN
Search…
0CHAIN
Explorer
ZWallet CLI
Zbox CLI
Deploying 0chain Locally on Linux
Blobber
0miner
0Chain Diagnostics Glossary
Zbox CLI
Zbox CLI is a GO-based command-line interface (CLI) tool used for managing storage operations on the 0Chain distributed storage platform. Built using 0Chain's GoSDK, the Zbox CLI tool provides a convenient way to interact with the blockchain, storage, and smart contracts.
 0Chain GoSDK provides APIs and utilities that developers can use to build Go applications to interact with 0Chain services. 0Chain GoSDK reduces the coding complexity to interact with dStorage and provides features for Zbox CLI such as storage allocation, downloading, and sharing of files and folders on the 0Chain dStorage platform.
Zbox CLI also includes helpful utilities on top of the 0Chain APIs that provide additional features and functionality. For example, Zbox CLI provides a self-explaining "help" option that lists commands and parameters they need to perform the intended action.
Features
Allocation Management
Zbox CLI provides a simple way to create and manage allocations for file storage.
File Management
Another feature offered by Zbox CLI is file management. You can upload, download and delete files from dStorage. Not only that, you can even share encrypted files.
Pool Management
With the help of Zbox CLI, you can manage pools. You can create read pools, check pool info and even lock tokens in the read pool.
Wallet Management
Zbox CLI automatically creates a wallet if no wallet is present. You can check your wallet balance and also view the wallet information. 
Get Started
This section covers Zbox CLI concepts, repository configuration, and installation. Check out these videos for reference.
Concepts
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 0chain 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 where all the data files are stored.
System requirements
To properly build components, you must have a Machine setup with the following requirements:
Windows, Linux, Mac OS (Linux with ubuntu 18.04 preferred)
4 vCPU, 8 Gb Memory at minimum
50 GB of space to store the Zbox build components. ‌
We will be building and describing Zbox CLI capabilities on Ubuntu Linux.
So If you want to build Zbox CLI on other platforms.
Follow this guide for Windows and other Platforms and move straight to the Creating a Storage Allocation​
Prerequisites
Installing and running the Zbox requires deployment-specific dependencies to be preinstalled‌
GoLang Binaries
Linux built-in Wget tool is used to fetch the golang archive from the google server using the command
1
wget https://golang.org/dl/go1.17.3.linux-amd64.tar.gz
Copied!
Tar command is used to extract the group of files into a usr/local directory
1
tar -C /usr/local -xzf go1.17.3.linux-amd64.tar.gz
Copied!
Original Archive is removed using
1
rm go1.17.linux-amd64.tar.gz
Copied!
Path Variable is set to usr/local directory using
1
export PATH=$PATH:/usr/local/go/bin
Copied!
Build-Essential
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
1
sudo apt update
Copied!
Get Build-essential package
1
sudo apt-get install build-essential
Copied!
Git
Git is required to retrieve and clone the Zbox repository. Install Git by using the command
1
sudo apt install git
Copied!
Building Zbox
1.Clone the Zbox Repository using the command
1
git clone https://github.com/0chain/zboxcli.git
Copied!
2.Navigate into zboxcli directory using
1
cd zboxcli
Copied!
3.Use the make install command to compile the source code .
1
make install
Copied!
This might take a couple of minutes. Sample output after completion of make command
Configure Zbox network
Configuration for the 0chain network by default is stored in network/one.yaml file of the zbox github repo which we will copy to a new config.yaml file in our local system . The config.yaml file and all the other Zbox component information will be stored in a  .zcn folder located in the home directory of the file system.
1.Make a new .zcn folder in the home Linux directory using
1
mkdir $HOME/.zcn
Copied!
2. Copy the content from one.yaml to a new config.yaml file using
1
cp network/one.yaml $HOME/.zcn/config.yaml
Copied!
3. To verify whether the config.yaml exists and network configuration is stored properly. Check the config.yaml details using the command
1
nano config.yaml
Copied!
Response :
1
---
2
block_worker: https://one.devnet-0chain.net/dns
3
signature_scheme: bls0chain
4
min_submit: 50
5
min_confirmation: 50
6
confirmation_chain_length: 3
7
max_txn_query: 5
8
query_sleep_time: 5
9
# # OPTIONAL - Uncomment to use/ Add more if you want
10
# preferred_blobbers:
11
#   - http://one.devnet-0chain.net:31051
12
#   - http://one.devnet-0chain.net:31052
Copied!
Change Zbox network 
1.Open the config.yaml  file located at $HOME/.zcn path of your system. The config.yaml file contents should be similar to the code snippet below :
1
---
2
block_worker: https://one.devnet-0chain.net/dns
3
signature_scheme: bls0chain
4
min_submit: 50
5
min_confirmation: 50
6
confirmation_chain_length: 3
7
max_txn_query: 5
8
query_sleep_time: 5
9
# # OPTIONAL - Uncomment to use/ Add more if you want
10
# preferred_blobbers:
11
#   - http://one.devnet-0chain.net:31051
12
#   - http://one.devnet-0chain.net:31052
13
#   - http://one.devnet-0chain.net:31053
Copied!
Zbox connects to the 0Chain 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.
2. Change the block_worker field for the desired network. In this case we will change it to beta.0chain.net. After changes it should look similar to the file below:
1
---
2
block_worker: https://beta.0chain.net/dns
3
signature_scheme: bls0chain
4
min_submit: 50
5
min_confirmation: 50
6
confirmation_chain_length: 3
7
max_txn_query: 5
8
query_sleep_time: 5
9
# # OPTIONAL - Uncomment to use/ Add more if you want
10
# preferred_blobbers:
11
#   - http://beta.0chain.net:31051
12
#   - http://beta.0chain.net:31052
13
#   - http://beta.0chain.net:31053   
Copied!
Starting Zbox
Start the Zbox by navigating back to the zboxcli directory using
1
cd zboxcli
Copied!
and type
1
./zbox
Copied!
On a successful run you will see a help section:
Creating a Storage Allocation
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
1
 ./zbox register
Copied!
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
1
git clone https://github.com/0chain/zwalletcli.git
2
cd zwalletcli
3
make install
Copied!
After a successful build, running the ./zwalletcommand will output a help section.
3.Now get the test tokens into your wallet by using
1
 ./zwallet faucet --methodName pour --input "{Pay day}"
Copied!
On Successful response:
1
Execute faucet smart contract success with txn :  50e6cf293567e456527a13a6981f1188fb6eb6b930c805c7ddba5e7e26ba9e6f
2
​
Copied!
4.Check Token balance in zwallet using the
1
./zwallet getbalance
Copied!
Response-
1
Balance: 1 (1.46 USD)
Copied!
6.Once the wallet has an available balance, you can create a storage allocation by using the Zbox newallocationcommand. To understand the syntax type
1
./zbox newallocation --help
Copied!
This will output the mandatory and optional flags that need to be added with the newallocationcommand.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:
1
./zbox newallocation --lock 0.5
Copied!
​ Successful Response will create an allocation with allocation ID:
Here allocation ID is fd642333e6fbe484108485e1d71c3f8ad781b049fe5eb98dd8bf1a09cc23aba8
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.
1
./zbox listallocations
Copied!
You will see your allocation ID listed with its specifications.
1
                                 ID                                |    SIZE    |          EXPIRATION           | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED |   R  PRICE   |   W  PRICE
2
+------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+--------------+--------------+
3
  
4
  fd642333e6fbe484108485e1d71c3f8ad781b049fe5eb98dd8bf1a09cc23aba8 | 2147593648 | 2021-06-07 17:47:19 +0000 UTC |          2 |            2 | false     | false    | 0.0417647055 | 0.0358823526
Copied!
Zbox Commands
​Global Flags​
​Assigning Variables​
​Creating and Managing Allocations​
​List Allocations​
​Custom Allocation​
​Update Allocation     
​Add a Curator​
​List Curators​
​Transfer allocation ownership​
​Create an Immutable Allocation​
​Get Allocation Details​
​List all files in an Allocation​
​Cancel Allocation​
​Finalize Allocation​
​Get Wallet Information​
​Get GoSDK and Zbox Version​
​List Blobbers​
​Uploading and Managing Files​
​Upload a file to dStorage​
​Uploading an Encrypted File to dStorage​
​Updating the contents of a file on dStorage​
​Sharing a file on dStorage​
​Downloading the file from dStorage​
​Copy uploaded files to another folder path on dStorage​
​Move uploaded files to another folder path on dStorage​
​Renaming Files on dStorage​
​List files from Blobbers​
​Get Stats for file in dStorage​
​Get metadata for stored file on dStorage​
​Get Download Cost for a file on dStorage​
​Get Cost for Uploading a file on dStorage​
​Advanced Zbox Commands​
​Sync ​
​Batch Upload Files to dStorage​
​Private File Sharing​
​Cancel Sharing of File for a Particular User​
​Private Directory Sharing​
​File Collaboration​
​Repair a file on dStorage​
​Asking the receiver to pay for download​
​Video Streaming​
Global Flags
Global Flags are parameters in zbox that can be used with any command to override the default configuration. zbox supports the following global parameters.
Flags
Description
Usage
--config string
Specify a zbox configuration file (default is $HOME/.zcn/config.yaml)
zbox [command] --config config1.yaml
--configDir string
Specify a zbox configuration directory (default is $HOME/.zcn)
zbox [command] --configDir /$HOME/.zcn2
-h, --help
Gives more information about a particular command.
zbox [command] --help
--network string
Specify a network file to overwrite the network details(default is $HOME/.zcn/network.yaml)
zbox [command] --network network1.yaml
--silent
Hides details as to what the particular zbox command is doing.
zbox [command] --verbose
--wallet string
Specify a wallet file or 2nd wallet (default is $HOME/.zcn/wallet.json)
zbox [command] --wallet wallet2.json
--wallet_client_id string
Specify a wallet client id (By default client_id specified in $HOME/.zcn/wallet.json is used)
zbox [command] --wallet_client_id 
--wallet_client_key string
Specify a wallet client_key (By default client_key specified in $HOME/.zcn/wallet.json is used)
zbox [command] --wallet_client_key  < client_key>
Assigning Variables
We will use the following variables using the export command for easy demonstration of zboxfunctionalities. 
1
export ALLOC = <your allocation ID >
Copied!
1
export AUTH = <your Auth ticket> 
Copied!
1
export lookuphash =<lookup hash for your uploaded file> 
Copied!
1
export local=<local path of the the file/directory on local computer >
Copied!
1
export remote=<remote path of the file/directory on dStorage>
Copied!
Creating and Managing Allocations 
List Allocations
./zbox listallocations show active storage allocations on dStorage. If you have not created any storage allocation we would suggest creating a storage allocation following this guide.
Command:
1
./zbox listallocations
Copied!
Response:
The response should contains the list of all your allocations with their specifications.(size, datashards, parityshards ,read price etc.)
1
                                 ID                                |    SIZE    |          EXPIRATION           | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R  PRICE | W  PRICE
2
+------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+
3
  52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC |          2 |            2 | false     | false    |     0.04 |     0.04
4
  637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef |  115000000 | 2021-04-23 04:11:44 +0000 UTC |          3 |            3 | false     | false    |     0.06 |     0.0
Copied!
Custom Allocation
Creating a custom allocation requires execution of ./zbox newallocation command with customized parameters. If you are creating your first allocation we would suggest reading Creating a Storage Allocation section first.
Required parameters for  creating a custom allocation can be viewed by using the command ./zbox newallocation --help
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
Example:
Let's create an allocation with 3 parity and data shards . Specify allocation expiration to 200hrs, change allocation size from default 2GB(2147483648) to near 1GB (1000000000), and lock tokens.
Command :
1
./zbox newallocation --data 3 --parity 3 --expire 200h --size 100000000 --lock 0.2
Copied!
Response:
1
Allocation created: 637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef
2
​
Copied!
Verify the custom allocation by using the ./zbox listallocationscommand
Output:
1
                                 ID                                |    SIZE    |          EXPIRATION           | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R  PRICE | W  PRICE
2
+------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+
3
  52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC |          2 |            2 | false     | false    |     0.04 |     0.04
4
  637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef |  100000000 | 2021-04-23 04:11:44 +0000 UTC |          3 |            3 | false     | false    |     0.06 |     0.06
5
​
Copied!
Your custom allocation should be listed with specifications.
Update Allocation
./zbox updateallocationcommand is used to update the existing allocation for various parameters,  Parameters for updating the allocation can be viewed by using the./zbox updateallocation --help command.
Here are the parameters:​
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
expiry
​
adjust storage expiration time
duration
free_storage
​
free storage marker file
string
lock
yes*
lock additional tokens in write pool
int
set_immutable
​
sets allocation so that data can no longer be modified
boolean
size
​
adjust allocation size
bytes
* only required if free_storage not set.
As mentioned in the above table , the allocation can be updated for size, expiry and immutability(set_immutable). We will provide an example for updating size and expiry of allocation below.
To know how to make an allocation immutable check Create an Immutable Allocation . 
Example: 
Let's edit an already created allocation for size and expiry.

Steps:
1.Get the allocation ID for updating the parameters using the listallocations command
    2. Use the updateallocation command and provide the new size .
1
./zbox updateallocation --allocation $ALLOC --size 15000000 
Copied!
3. Now provide the new expiry time
1
./zbox updateallocation --allocation $ALLOC --expiry 600h 
Copied!
Response:
1
Allocation updated with txId : 76bbff53ca986eac601b318ee0ee696a6499087d5aec68ec7e222ba5436fc797
2
​
Copied!
Add a curator
A curator can be added to transfer ownership of an allocation. Only a curator can change an allocation's ownership.
To add a curator using the addcurator command , following parameters are required :
Parameter 
Required
Description
Valid Values
allocation
yes
allocation id
string
curator
yes
Wallet Client ID of new curator to add to allocation
string
Steps:
1.Ask the Curator to share its Wallet Client ID using the getwallet command.
2. Export the new Curator Wallet Client ID to a variable.
1
export CURATOR_WALLET_CLIENT_ID=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
Copied!
 3.  Use the addcurator command
1
./zbox addcurator --curator $CURATOR_WALLET_CLIENT_ID --allocation $ALLOC   
Copied!
Response:
1
<CURATOR_WALLET_CLIENT_ID> added as a curator to allocation <ALLOC_ID>
Copied!
List Curators
Each allocation maintains a list of curators which can be viewed using the ./zbox get allocation command. To view the list of curators using the get command , following parameters are required :
Parameter 
Required
Description
Valid Values
allocation
yes
allocation id
string
 Steps:
1. Use the get command and pass the allocation ID of the allocation for which you want the list of curators .
1
./zbox get --allocation $ALLOC 
Copied!
2. The curators will be mentioned in the end of the response with their configuration:
(NOTE: The output below has been edited for length.)
1
allocation:
2
  id:              063e43f42abea8804f9f74684f90c7d7006c7398b32813de227fb29249fa2231
3
  tx:              1aef0e669af8b96d7240c3594643cca2b47a5a463d4381a5448168e15461f58e (latest create/update allocation transaction hash)
4
  data_shards:     2
5
  parity_shards:   2
6
  size:            2.0 GiB
7
  expiration_date: 2021-09-04 21:08:47 +0530 IST
8
  immutable:       true
9
  blobbers:
10
    - blobber_id:       00b9d31e17b96bd7594463785fbc44b5b62679876c3506f15ed9372ac5b9a21c
11
      base URL:         http://dev.0chain.net:31301
12
      size:             512.0 MiB
13
      min_lock_demand:  0.001257811
14
      spent:            0 (moved to challenge pool or to the blobber)
15
      penalty:          0 (blobber stake slash)
16
      read_reward:      0
17
      returned:         0 (on challenge failed)
18
      challenge_reward: 0 (on challenge passed)
19
      final_reward:     0 (if finalized)
20
      terms: (allocation related terms)
21
        read_price:                0.0251562201 tok / GB (by 64KB chunks)
22
        write_price:               0.0251562201 tok / GB
23
        min_lock_demand:           10 %
24
        max_offer_duration:        744h0m0s
25
        challenge_completion_time: 2m0s
26
curators: 
27
  9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
28
  e944c69d17c0d93631ae8e058958a3a983276874d83d19f0fe7049b1af5045d3
29
  read_price_range:          0-922337203.6854776 (requested)
30
  write_price_range:         0-922337203.6854776 (requested)
31
  challenge_completion_time: 2m0s (max)
32
  start_time:                2021-08-05 21:08:47 +0530 IST
33
  finalized:                 false
34
  canceled:                  false
35
  moved_to_challenge:        0
36
  moved_back:                0
37
  moved_to_validators:       0
38
  stats:
39
    total size:              2.0 GiB
40
    used size:               0 B
41
    number of writes:        0
42
    total challenges:        0
43
    passed challenges:       0
44
    failed challenges:       0
45
    open challenges:         0
46
    last challenge redeemed: 
47
  price:
48
    time_unit:   720h0m0s
49
    read_price:  0.0125903933 tok / GB (by 64KB)
50
    write_price: 0.2012497608 tok / GB / 720h0m0s
Copied!
Remove a curator
A curator can be removed for an allocation by using the removecurator command , 
Following parameters are required to remove a curator  :
Parameter 
Required
Description
Valid Values
allocation
yes
allocation id
string
curator
yes
Wallet Client ID of a curator to remove from  allocation
string
Steps:
1.Get the list of curators for an allocation using the List Curators command.
2. Export the Curator ID that has to be removed to a variable.
1
export CURATOR_WALLET_CLIENT_ID=<CURATOR_ID>
Copied!
 3.  Use the removecurator command
1
./zbox removecurator --curator $CURATOR_WALLET_CLIENT_ID --allocation $ALLOC   
Copied!
Response:
1
<CURATOR_WALLET_CLIENT_ID> removed as a curator to allocation <ALLOC_ID>
Copied!
Transfer allocation ownership
transferallocation changes the owner of an allocation. Only a curator, previously added through addcurator command can change an allocation's ownership. If the current owner wants to transfer ownership they have to first add themselves as a curator using addcurator.transferallocation does not move any funds, only changes the owner, and the owner's public key.
To transfer the ownership of an allocation using the transferallocation command, following parameters are required
Parameter
Required
Description
Valid Values
allocation
yes
Allocation id of the allocation whose ownership has to be changed
string
newowner
yes
Wallet Client ID of new Owner 
string
new_owner_key
yes
Wallet Public Key of the new Owner
string
Steps:
1.Ask the new owner to share its Wallet Client ID and Public Key using the getwallet command.
2. Export the new Owner Wallet Client ID to a variable.
1
export OWNER_WALLET_CLIENT_ID=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
Copied!
3. Export the new Owner Public Key to a variable
1
export OWNER_WALLET_PUBLIC_KEY=383a51ac8424d5079fa1402e26a3455a42ca9c03c8bff7d0f8eb0431d4f22b199b5ecae4405a5aa29c624c5299d79b8ba023c43e3d0599c2b60e74d445b3ae 
Copied!
4. Use the transferallocation command.
1
./zbox transferallocation --new_owner $OWNER_WALLET_CLIENT_ID --new_owner_key $OWNER_WALLET_PUBLIC_KEY --allocation $ALLOC
Copied!
Note: Only the curator can transfer ownership of allocation.
Response:
1
transferred ownership of allocation <ALLOC_ID> to <OWNER_WALLET_CLIENT_ID>
Copied!
Create an Immutable Allocation
You can prevent an allocation from any crud( create, read, update and delete) operations by making it immutable through the updateallocation command.
To create an immutable allocation using the updateallocation command , following parameters are required.
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
set_immutable
yes
Boolean for the immutable allocation. Has to be set to true for making the allocation immutable. 
boolean​
Steps:
1.Use the updateallocation command.
1
./zbox updateallocation --set_immutable true --allocation $ALLOC
Copied!
Response :
1
Allocation updated with txId : 1aef0e669af8b96d7240c3594643cca2b47a5a463d4381a5448168e15461f58e
2
​
Copied!
You can check whether the allocation has become immutable by uploading a file to the allocation. It should deny access with the following error
1
[ERROR]  2021/09/25 01:53:41.310951 chunked_upload_blobber.go:75: 
2
http://0.fra.zcn.zeroservices.eu:5054 
3
Upload error response: 400{"code":"immutable_allocation","error":"immutable_allocation:
4
 Cannot write to an immutable allocation"}
5
​
Copied!
Get Allocation Details
./zbox get command is used to get detailed information about the allocation such as total size ,used size, number of challenges, etc . 
 The command can accept the following parameters :
Parameter
Required
Description
Valid Values
--allocation
yes
Allocation ID of an allocation
string
--json
​
Use this flag to print detailed allocation information as json data.
durati
Example Command:
1
./zbox get --allocation $ALLOC
Copied!
Here $ALLOC variable refers to the allocation id specified.
Response:
The response should contain information about blobbers allocated and stats for the allocation as mentioned below.
1
​
2
allocation:
3
  id:              52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059
4
  tx:              52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 (latest create/update allocation transaction hash)
5
  data_shards:     2
6
  parity_shards:   2
7
  size:            2.0 GiB
8
  expiration_date: 2021-05-14 17:50:59 +0000 UTC
9
  blobbers:
10
    - blobber_id:       68cd771c6a34f2b6bf61980fc86b9255979beda9d5375377410aadafdf257c5c
11
      base URL:         http://one.devnet-0chain.net:31303
12
      size:             512.0 MiB
13
      min_lock_demand:  0.0005
14
      spent:            0.0000061042 (moved to challenge pool or to the blobber)
15
      penalty:          0 (blobber stake slash)
16
      read_reward:      0.0000061035
17
      returned:         0.0000000002 (on challenge failed)
18
      challenge_reward: 0 (on challenge passed)
19
      final_reward:     0 (if finalized)
20
      terms: (allocation related terms)
21
        read_price:                0.01 tok / GB (by 64KB chunks)
22
        write_price:               0.01 tok / GB
23
        min_lock_demand:           10 %
24
        max_offer_duration:        744h0m0s
25
        challenge_completion_time: 2m0s
26
    - blobber_id:       34934babf0781c21736023ff89bc554928d77c028a968ef7344a460611d5a8d2
27
      base URL:         http://one.devnet-0chain.net:31302
28
      size:             512.0 MiB
29
      min_lock_demand:  0.0005
30
      spent:            0.0000061042 (moved to challenge pool or to the blobber)
31
      penalty:          0 (blobber stake slash)
32
      read_reward:      0.0000061035
33
      returned:         0.0000000002 (on challenge failed)
34
      challenge_reward: 0 (on challenge passed)
35
      final_reward:     0 (if finalized)
36
      terms: (allocation related terms)
37
        read_price:                0.01 tok / GB (by 64KB chunks)
38
        write_price:               0.01 tok / GB
39
        min_lock_demand:           10 %
40
        max_offer_duration:        744h0m0s
41
        challenge_completion_time: 2m0s
42
  read_price_range:          0-922337203.6854776 (requested)
43
  write_price_range:         0-922337203.6854776 (requested)
44
  challenge_completion_time: 2m0s (max)
45
  start_time:                2021-04-14 17:50:59 +0000 UTC
46
  finalized:                 false
47
  canceled:                  false
48
  moved_to_challenge:        0.0000000028
49
  moved_back:                0.0000000008
50
  moved_to_validators:       0
51
  stats:
52
    total size:              2.0 GiB
53
    used size:               324 B
54
    number of writes:        40
55
    total challenges:        23
56
    passed challenges:       10
57
    failed challenges:       11
58
    open challenges:         2
59
    last challenge redeemed: 783d50d5ff63b87e99eb815044af02d77a2048761d7c732dd674bd3d13a24b5b
60
  price:
61
    time_unit:   720h0m0s
62
    read_price:  0.0050048828 tok / GB (by 64KB)
63
    write_price: 0.08 tok / GB / 720h0m0s
64
​
Copied!
List all files in an Allocation
./zbox list-all command is used to list all the files stored with an allocation. Additional Parameters can be viewed using the ./zbox list-all --help command.
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
Command :
1
./zbox list-all --allocation $ALLOC 
Copied!
Response :
1
{"name":"myfiles","path":"/myfiles","type":"d","size":40,"hash":""},
2
{"name":"hello.txt","path":"/myfiles/hello.txt","type":"f","size":40,"hash":"a591754c7165c947704e8e378f8fb652867a61c1"}]
Copied!
Cancel Allocation
./zbox alloc-cancel immediately return all remaining tokens from challenge pool back to the allocation's owner and cancels the allocation. If blobbers already got some tokens, the tokens will not be returned. Remaining min lock payment to the blobber will be funded from the allocation's write pools.
Note : Cancelling an allocation can only occur if the amount of failed challenges exceed a preset threshold.
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
Command :
1
./zbox alloc-cancel --allocation $ALLOC
Copied!
Response :
1
Allocation canceled with txId : 62ff90a533d63023fcbc3244be9d0f6fd1f8c737fd24c9474dd24055cdb60e39
Copied!
Finalize Allocation
./zbox alloc-fini command is used to finalize an allocation after it is expired. An allocation becomes expired when the expiry time has passed followed by a period equal to the challenge completion period. Any remaining min lock payment to the blobber will be funded from the allocation's write pools. Any available money in the challenge pool returns to the allocation's owner.
Note : An allocation can be finalized by the owner or one of the allocation blobbers.
Parameter
Required
Description
Valid Values
allocation
yes
allocation id
string
Command:
1
./zbox alloc-fini --allocation $ALLOC
Copied!
Get Wallet Information
Use the getwalletcommand to get additional wallet information including Public Key, Client ID , Encryption Public Key required for Proxy Re-Encryption.
Parameter
Required
Description
default
Valid values
json
no
print response in json format
false
boolean
Command
1
./zbox getwallet 
Copied!
Response
1
PUBLIC KEY | CLIENTID | ENCRYPTION PUBLIC KEY              
2
----------------------------------------------------------------------------------------------------------------------------------
3
  9332ca57e335f286f1d3edc2dd7589594dbb4b30fae19766b5f67712520fde09f8eac6a979f3574ccd89e5680a6b47dcdc88ae0544dc30633cce2a7831ce0014 
4
  | 9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b 
5
  | bKodfMsHfUNXr/rr8msPe4Rv2nLP34aUIasK44p7tRs=  
Copied!
Get GoSDK and Zbox version
The version of Zbox and Gosdk can be fetched using the ./zbox version command.
Command:
1
./zbox version
Copied!
Response:
1
Version info:
2
        zbox....:  v1.0.1-180-g25f8af1
3
        gosdk...:  v1.2.0
4
​
Copied!
List blobbers
Show active blobbers in dStorage .‌
Command
1
  ./zbox ls-blobbers
Copied!
Response usually outputs several blobbers. Here is a info for a single blobber
1
- id:                    00b9d31e17b96bd7594463785fbc44b5b62679876c3506f15ed9372ac5b9a21c
2
  url:                   http://dev.0chain.net:31301
3
  used / total capacity: 92.4 GiB / 100.0 GiB
4
  last_health_check:	  1629741994
5
  terms:
6
    read_price:          0.016958379 tok / GB
7
    write_price:         0.016958379 tok / GB / time_unit
8
    min_lock_demand:     0.1
9
    cct:                 2m0s
10
    max_offer_duration:  744h0m0s
11
​
Copied!
Uploading and Managing Files
Uploading a file to dStorage
./zbox upload command is used to upload a file on dStorage. Parameters for uploading a file to dStorage can be viewed by using the ./zbox upload --help command.
Here are the Parameters :
Parameter
Required
Description
Default
Valid values
allocation
yes
allocation id, sender must be allocation owner
​
string
commit
no
save metadata to blockchain
false
boolean
encrypt
no
encrypt file before upload
false
boolean
localpath
yes
local path of the file to upload
​
file path
remotepath
yes
remote path to upload file to, use to access file later
​
string
thumbnailpath
no
local path of thumbnail
​
​
file path
Example :
Let's upload an info.txt file to allocation, the local path for the file is mapped to a local variable and the remote directory is mapped to a remote variable which is  myfiles/info.txt.
Sample Command:
1
./zbox upload --localpath $local --remotepath $remote --allocation $ALLOC
Copied!
Response
1
 24 / 24 [=======================================================================================================================================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = info.txt
3
​
Copied!
Verify whether the uploaded file is available on dStorage using list command required parameters are allocation ID and remote path
1
./zbox list --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
  TYPE |   NAME   |       PATH        | SIZE | NUM BLOCKS |LOOKUP HASH | 
2
  IS ENCRYPTED | DOWNLOADS PAYER
3
+------+----------+-------------------+------+------------+-----------------------------------------------
4
  f    | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c4322
5
  69eeb7def555f1f8b9b9a28bd9611362c | NO | owner
6
​
Copied!
The response yields a lookuphash which works as a unique identifier for the uploaded file. Since you uploaded the file, the download payer section will show it as owner.
Copy and mark your lookup hash to a variable as it will be used for performing other file operations
export LOOKUPHASH=f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c
Uploading an Encrypted File to dStorage
Parameters for encrypting and uploading a file to dStorage are almost the same as uploading a file on dStorage and only requires an additional --encrypt flag with the command.
For instance if we want to encrypt and upload a sample info.txt file the command would be:
Command:
1
./zbox upload --encrypt --localpath $local --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
24 / 24 [================================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = info.txt
Copied!
To verify whether the file is encrypted and uploaded to dstorage use the list command :
1
./zbox list --allocation $ALLOC --remotepath $remote
Copied!
Response:
1
 TYPE |   NAME   |       PATH        | SIZE | NUM BLOCKS |LOOKUP HASH 
2
 | IS ENCRYPTED | DOWNLOADS PAYER
3
+------+----------+-------------------+------+------------+-----------------------------------------------
4
  f    | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c432269
5
  eeb7def555f1f8b9b9a28bd9611362c | YES | owner
Copied!
Scroll right in the response and check the IS ENCRYPTED section, it will say YES if the file is encrypted.
Updating the contents of a file on dStorage
Use ./zbox update command to update the content of an existing file in the remote path. Like upload command. Only the owner of the allocation or a collaborator can update a file. To add collaborators to an allocation, check File Collaboration.​
Parameters for updating the contents of the file on dStorage can be seen by typing ./zbox update --help
Here are the parameters:
Parameter
Required
Description
Default
Valid values
allocation
yes
allocation id
​
string
encrypt
no
encrypt file before upload
false
boolean
localpath
yes
local file to upload
​
file path
remotepath
yes
remote file to upload
​
string
thumbnailpath
no
local fumbnail file to upload
​
file path
commit
no
save meta data to blockchain
false
boolean
 Sample Command:
1
./zbox update --localpath $local --remotepath $remote --allocation $ALLOC  
Copied!
Response:
1
 76 / 76 [=======================================================================================================================================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = info.txt
3
​
Copied!
Verify the contents of updated file on dStorage using the list command.
1
./zbox list --remotepath $remote --allocation $ALLOC
Copied!
Sample Response:
1
  TYPE |   NAME   |       PATH    | SIZE | NUM BLOCKS | LOOKUP HASH 
2
  | IS ENCRYPTED | DOWNLOADS PAYER
3
​
4
  f    | info.txt | /myfiles/info.txt | 76 |  4 | f15383a1130bd2fae1e52a7a15c432
5
  269eeb7def555f1f8b9b9a28bd9611362c | NO | owner
6
​
Copied!
Sharing a File on dStorage
Zbox supports sharing of files using Authorization tokens. Sharing can be encrypted or not encrypted for this section we will describe the non-encrypted share functionality. For encrypted shared functionality have a look at Private Sharing .
./zbox share command is used to generate an authtoken that provides authorization to the holder to the specified file on the remotepath. Parameters for sharing the file can be viewed using the ./zbox share --help
The parameters are:
Parameter
Required
Description
Valid values
allocation
yes
allocation id
string
clientid
no
id of user to share file with, leave blank for public share
string
encryptionpublickey
no
public key of the client to share file with, required if clientId
string
expiration-seconds
no
seconds before auth ticket expires
int
remotepath
yes
remote path of file to share
string
revoke
no
revoke share for remote path
flag
 Command:
1
./zbox share --remotepath $remote --allocation $ALLOC
Copied!
Response:
1
Auth token :eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3NTNkMjlkODE5ODkyNmZhYzJlZDQz
2
YWNjMzcwNDhhNzFmZmYzNDg2YTQ4N2ZjNmVlZDU0ZWFkNDY5YWQxNTkiLCJhbGxvY2F0aW9uX2lkIjoiN
3
TJmYjliNTkyNmMwNmU0M2E5MjkwZTlkN2FkMzIxN2E0YWVlNTFjOTQ2ODRiYWYwZmMxNzRhYTQxYWJlNj
4
A1OSIsImZpbGVfcGF0aF9oYXNoIjoiZjE1MzgzYTExMzBiZDJmYWUxZTUyYTdhMTVjNDMyMjY5ZWViN2Rl
5
ZjU1NWYxZjhiOWI5YTI4YmQ5NjExMzYyYyIsImZpbGVfbmFtZSI6ImluZm8udHh0IiwicmVmZXJlbmNlX3
6
R5cGUiOiJmIiwiZXhwaXJhdGlvbiI6MTYyNjIwNDM5NSwidGltZXN0YW1wIjoxNjE4NDI4Mzk1LCJyZV9
7
lbmNyeXB0aW9uX2tleSI6IiIsInNpZ25hdHVyZSI6ImM1ZDViYzY3M2Q1NTNmZmM3M2FhNTg2MDkwNDgw
8
ODVlMjZhN2UyZmUzNTQ2MjA5OTlhNTk3NDdhNDFlNmNiMWQifQ==
9
​
10
​
Copied!
The response will yield an Auth token which can be shared publicly to users for downloading the file. You can use an export command and mark your Auth token to a variable using:
1
export AUTH= eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3NTNkMjlkODE5ODkyNmZhYzJlZDQzYWNj
2
MzcwNDhhNzFmZmYzNDg2YTQ4N2ZjNmVlZDU0ZWFkNDY5YWQxNTkiLCJhbGxvY2F0aW9uX2lkIjoiNTJmYjl
3
iNTkyNmMwNmU0M2E5MjkwZTlkN2FkMzIxN2E0YWVlNTFjOTQ2ODRiYWYwZmMxNzRhYTQxYWJlNjA1OSIsIm
4
ZpbGVfcGF0aF9oYXNoIjoiZjE1MzgzYTExMzBiZDJmYWUxZTUyYTdhMTVjNDMyMjY5ZWViN2RlZjU1NWYxZ
5
jhiOWI5YTI4YmQ5NjExMzYyYyIsImZpbGVfbmFtZSI6ImluZm8udHh0IiwicmVmZXJlbmNlX3R5cGUiOiJmIi
6
wiZXhwaXJhdGlvbiI6MTYyNjIwNDM5NSwidGltZXN0YW1wIjoxNjE4NDI4Mzk1LCJyZV9lbmNyeXB0aW9uX2tle
7
SI6IiIsInNpZ25hdHVyZSI6ImM1ZDViYzY3M2Q1NTNmZmM3M2FhNTg2MDkwNDgwODVlMjZhN2UyZmUzNTQ2MjA5O
8