Creating and Managing Allocations

​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.
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>
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:
./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
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 :
./zbox newallocation --data 3 --parity 3 --expire 200h --size 100000000 --lock 0.2
Response:
Verify the custom allocation by using the ./zbox listallocationscommand
Output:
                                 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.
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
--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.Get the allocation ID for updating the parameters using the listallocations command
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:
Forbid Options in Allocation
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 :
To test functionality try uploading file to allocation. You should get the following response
Upload failed. this options for this file is not permitted for this allocation: 
file_option_not_permitted.
Free Allocation
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 storage
free_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.json
Response:
Allocation created: cb3a1efafa3e374718e51710d4ccfabd2f242b8e53cc2960e142d67164f1ea0c
Free storage assigner
./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

To demonstrate lets provide permission to 0box to generate free allocation.
./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 and namevariable in 0box.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
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.
export CURATOR_WALLET_CLIENT_ID=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
3. Use the addcurator command
./zbox addcurator --curator $CURATOR_WALLET_CLIENT_ID --allocation $ALLOC   
Sample Response:
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 .
./zbox get --allocation $ALLOC 
2. The curators will be mentioned in the end of the response with their configuration:
(NOTE: The output below has been edited for length.)
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.
export CURATOR_WALLET_CLIENT_ID=<CURATOR_ID>
3. Use the removecurator command
./zbox removecurator --curator $CURATOR_WALLET_CLIENT_ID --allocation $ALLOC   
Sample Response:
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.
export OWNER_WALLET_CLIENT_ID=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b
3. Export the new Owner Public Key to a variable
export OWNER_WALLET_PUBLIC_KEY=383a51ac8424d5079fa1402e26a3455a42ca9c03c8bff7d0f8eb0431d4f22b199b5ecae4405a5aa29c624c5299d79b8ba023c43e3d0599c2b60e74d445b3ae 
4. Use the transferallocation command.
./zbox transferallocation --new_owner $OWNER_WALLET_CLIENT_ID --new_owner_key $OWNER_WALLET_PUBLIC_KEY --allocation $ALLOC
Note: Only the curator can transfer ownership of allocation.
Sample Response:
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.
./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"}
​
Get Allocation Details
./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
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 :
./zbox list-all --allocation $ALLOC 
Response :
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 :
./zbox alloc-cancel --allocation $ALLOC
Response :
Allocation canceled with txId : 62ff90a533d63023fcbc3244be9d0f6fd1f8c737fd24c9474dd24055cdb60e39
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:
./zbox alloc-fini --allocation $ALLOC
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
./zbox getwallet 
Response:
Get GoSDK and Zbox version
The version of Zbox and Gosdk can be fetched using the ./zbox version command.
Command:
./zbox version
Response:
List blobbers
Show active blobbers in dStorage .‌
Command
  ./zbox ls-blobbers
Response usually outputs several blobbers and their specifications.
Sample Response:
List All Validators
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 %
Get Validator Configuration
./zbox validator-info command is used to get a particular validator configuration . Here are the parameters for the command . 
Parameter
Required
Text
--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 :  
Total Stored Data
./zbox total-stored-data returns the summation of all the Size fields in all the files stored across blobbers.
Sample Command:
./zbox total-stored-data
Sample Response:
total stored data: 673504

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>

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

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

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

Parameter	Required	Description	Valid Values
allocation	yes	allocation id	string
curator	yes	Wallet Client ID of new curator to add to allocation	string

Parameter	Required	Description	Valid Values
allocation	yes	allocation id	string

Parameter	Required	Description	Valid Values
allocation	yes	allocation id	string
curator	yes	Wallet Client ID of a curator to remove from allocation	string

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

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

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

Parameter	Required	Description	Valid Values
allocation	yes	allocation id	string

Parameter	Required	Description	Valid Values
allocation	yes	allocation id	string

Parameter	Required	Description	Valid Values
allocation	yes	allocation id	string

Parameter	Required	Description	default	Valid values
json	no	print response in json format	false	boolean

Parameter	Required	Text
--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

Get Started

Uploading and Managing Files

Last modified 8d ago