Creating and Managing Allocations
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> |
We will use the following variables using the export command for easy demonstration of
zbox
functionalities.export ALLOC = <your allocation ID >
export AUTH = <your Auth ticket>
export lookuphash =<lookup hash for your uploaded file>
export local=<local path of the the file/directory on local computer >
export remote=<remote path of the file/directory on dStorage>
./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:
./zbox listallocations
Response:
The response should contains the list of all your allocations with their specifications.(size, datashards, parityshards ,read price etc.)
ID | SIZE | EXPIRATION | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R PRICE | W PRICE
+------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+
52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC | 2 | 2 | false | false | 0.04 | 0.04
637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef | 115000000 | 2021-04-23 04:11:44 +0000 UTC | 3 | 3 | false | false | 0.06 | 0.0
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 :
./zbox newallocation --data 3 --parity 3 --expire 200h --size 100000000 --lock 0.2
Response:

Verify the custom allocation by using the
./zbox listallocations
commandOutput:
ID | SIZE | EXPIRATION | DATASHARDS | PARITYSHARDS | FINALIZED | CANCELED | R PRICE | W PRICE
+------------------------------------------------------------------+------------+-------------------------------+------------+--------------+-----------+----------+----------+----------+
52fb9b5926c06e43a9290e9d7ad3217a4aee51c94684baf0fc174aa41abe6059 | 2147483648 | 2021-05-14 17:50:59 +0000 UTC | 2 | 2 | false | false | 0.04 | 0.04
637191e4cc5d78c5e8f3943b96a7de6509ec7cba28fd593d302a86b4c062a6ef | 100000000 | 2021-04-23 04:11:44 +0000 UTC | 3 | 3 | false | false | 0.06 | 0.06
Your custom allocation should be listed with specifications.
./zbox updateallocation
command 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 |
--forbid_copy | | specify if the users cannot copy object from this allocation | |
--forbid_update | | specify if the users cannot update objects in this allocation | |
--forbid_delete | | specify if the users cannot delete objects from this allocation | |
--forbid_move | | specify if the users cannot move objects from this allocation | |
--forbid_rename | | specify if the users cannot rename objects in this allocation | |
--forbid_upload | | specify if users cannot upload to this allocation | |
*
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.
2. Use the
updateallocation
command and provide the new size ../zbox updateallocation --allocation $ALLOC --size 15000000
3. Now provide the new expiry time
./zbox updateallocation --allocation $ALLOC --expiry 600h
Sample Response:
.gif?alt=media)
There are various operations which you can forbid on an allocation. Forbid flag works with update allocation command. Check its working first.
Here are the operations:
Parameter | Description |
---|---|
--forbid_copy | specify if the users cannot copy object from this allocation |
--forbid_update | specify if the users cannot update objects in this allocation |
--forbid_delete | specify if the users cannot delete objects from this allocation |
--forbid_move | specify if the users cannot move objects from this allocation |
--forbid_rename | specify if the users cannot rename objects in this allocation |
--forbid_upload | specify if users cannot upload to this allocation |
Here is a sample command for
--forbid_upload .
Other parameters can be done same way../zbox updateallocation --allocation $ALLOC --forbid_upload
Sample Response :

Upload failed. this options for this file is not permitted for this allocation:
file_option_not_permitted.
free_storage
is an additional parameter of ./zbox newallocation
command that allows you to create free allocations using json storage markers. Entities can give free 0chain
storage in the form of markers. A typical json free storage marker file looks similar to this{
"assigner": "my_corporation",
"recipient": "f174cdda7e24aeac0288afc2e8d8b20eda06b18333efd447725581dc80552977",
"free_tokens": 2.1,
"timestamp": 2000000,
"signature": "9edb86c8710d5e3ee4fde247c638fd6b81af67e7bb3f9d60700aec8e310c1f06"
}
Here:
assigner
Name of the entity providing the free storage.recipient
: This contains the wallet id of the recipient who is provided free storagefree_tokens
The maximum amount of free tokens available for creating an allocation. When creating a new allocation the free tokens will be split between the allocation's write pool, and a new read pool; the ratio of this split configured on the blockchain.timestamp
A unique timestamp. Used to prevent multiple applications of the same marker.signature
Signed by the assigner, validated using the stored public key on the blockchain. Note: To understand how free storage is assigned check free storage assigner command.Syntax./zbox newallocation --free_storage {path/to/marker_json_file}Sample Command./zbox newallocation --free_storage markers/marker.jsonResponse:Allocation created: cb3a1efafa3e374718e51710d4ccfabd2f242b8e53cc2960e142d67164f1ea0c
./zbox add
command provide permission to chain applications to generate free allocation.Parameters:
Flags | Description | Required |
--key | The wallet public key for signing free storage markers. This is the public key of wallet of the chain owner . | yes |
--limit | Defines the maximum number of tokens that can be used to generate a free allocation (default is 1) | yes |
--max | Total number of tokens free allocations can utilize (default is 1) | yes |
--name | Account name that will be assigning free storage. | yes |
./zbox add --name 0chain --limit 2.1 --max 3000 --key $CHAIN_OWNER_WALLET_PUBLIC_KEY
Here
- The
./zbox add
command should be called from chain wallet owner only. - 0chain is the account name that will be assigning free storage. You can provide your chain/account name for better understanding .
- 2.1 is the maximum amount of ZCN tokens that can be used by 0box to create each allocation
- 3000 is the total number of ZCN tokens that are usable by 0box for creating allocations.
- key is the public key of the wallet of chain owner .
- Make sure
freestorage.public_key
andname
variable in0box.yaml
located inside (0box/docker.local/config) directory is similar to public key and account name of chain wallet owner.
Sample Successful Response:
0chain added as free storage assigner
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.
./zbox updateallocation --set_immutable true --allocation $ALLOC
Response :
Allocation updated with txId : 1aef0e669af8b96d7240c3594643cca2b47a5a463d4381a5448168e15461f58e
You can check whether the allocation has become immutable by uploading a file to the allocation. It should deny access with the following error
[ERROR] 2021/09/25 01:53:41.310951 chunked_upload_blobber.go:75:
http://0.fra.zcn.zeroservices.eu:5054
Upload error response: 400{"code":"immutable_allocation","error":"immutable_allocation:
Cannot write to an immutable allocation"}
./zbox getallocation
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:
./zbox getallocation --allocation $ALLOC
Here $ALLOC variable refers to the allocation id specified.
The response should contain information about blobbers allocated and stats for the allocation as mentioned below.

Get 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 :
./zbox list-all --allocation $ALLOC
Response :

./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 :
./zbox alloc-cancel --allocation $ALLOC
Response :
Allocation canceled with txId : 62ff90a533d63023fcbc3244be9d0f6fd1f8c737fd24c9474dd24055cdb60e39
./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:
./zbox alloc-fini --allocation $ALLOC
Use the
getwallet
command 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
./zbox getwallet
Response:

The version of Zbox and Gosdk can be fetched using the
./zbox version
command.Command:
./zbox version
Response:

Show active blobbers in dStorage .
Command
./zbox ls-blobbers
Response usually outputs several blobbers and their specifications.
Sample Response:

List all active validators on the network
Command:
./zbox ls-validators
Response :

Formatted Shortened Response:
id: b9f4f244e2e483548795e42dad0c5b5bb8f5c25d70cadeafc202ce6011b7ff8c
url: https://demo.zus.network/validator03/
settings:
delegate_wallet: 9c693cb14f29917968d6e8c909ebbea3425b4c1bc64b6732cadc2a1869f49be9
min_stake: 1.000 ZCN
max_stake: 100.000 ZCN
num_delegates: 50
service_charge: 30 %
id: c025fad27d3daa6fbe6a10ef38f1075dc5a6386760951816ece953391ff9804b
url: https://demo.zus.network/validator02/
settings:
delegate_wallet: 9c693cb14f29917968d6e8c909ebbea3425b4c1bc64b6732cadc2a1869f49be9
min_stake: 1.000 ZCN
max_stake: 100.000 ZCN
num_delegates: 50
service_charge: 30 %
./zbox validator-info
command is used to get a particular validator configuration . Here are the parameters for the command . Parameter | Required | Description |
---|---|---|
--validator_id | Yes | Find validator id through List All Validators command. This will list all the validators on the network |
--json | Optional | Print response as json data |
--help | | Provide information about the command |
Sample Command :
./zbox validator-info --validator_id $VALIDATOR_ID
Sample Response :

./zbox kill-blobber
command deactivates a blobber to avoid storage of data .Required parameters are Parameter | Required | Description |
---|---|---|
--id | yes | |
--h, --help | no | Help will list all the parameters related to the command. |
Sample Command :
./zbox kill-blobber --id $BLOBBER_ID --wallet $CHAIN_OWNER_WALLET
Note : Kill Blobber command should be evoked from chain owner wallet only
Sample Response :
killed blobber $BLOBBER_ID
./zbox kill-validator
command deactivates a specific validator available on the network. Required parameters are : Parameter | Required | Description |
---|---|---|
--id | yes | Validator ID of a specific validator to deactivate.Validator ID can be retrieved using List Validators command. |
--h,--help | no | Help will list all the parameters related to the command. |
Sample Command
./zbox kill-validator --id $VALIDATOR_ID --wallet $CHAIN_OWNER_WALLET
Note : Kill Validator command should be evoked from chain owner wallet only
Sample Response :
killed validator, id: $VALIDATOR_ID
Last modified 1mo ago