Creating and Managing Allocations

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

--fee float

Transaction fee for the given transaction(if unset, it will be set to blockchain min fee)

zbox[command] --fee 0.5

-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

(default false) Do not show interactive sdk logs (shown by default)

zbox [command] --silent

--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>

--withNonce int

nonce that will be used in transaction (default is 0)

zbox [command] --withNonce 1

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.

To Unforbid an operation after forbiding:

Sample Command:

./zbox updateallocation --allocation $ALLOC --forbid_upload false

Add Blobber

Use add_blobber flag with update allocation command to add blobber to allocation.The new blobber will be added as a parity blobber.For more details check how a file is stored on blobbers.

Here are the necessary parameters for adding blobber.

Parameter
Description
Valid Values

--allocation

Provide Allocation ID for adding blobber to allocation

string

--add_blobber

Provide Blobber ID to add. Can be fetched using List blobbers.

string

Sample Command:

./zbox updateallocation --allocation $ALLOC --add_blobber 98f14362f075caf467653044cf046eb9e8a5dfee88dc8b78cad1891748245003

Sample Response:

Allocation updated with txId : d853a82907453d37ed978b9fc1a55663be99bb351d18cca31068c0dc95566edd

Note: Files will automatically be uploaded,splitted, and stored on added blobber.

Note: An allocation is already hosted on a set of blobbers. To find a blobber that is available to add you should exclude the current set of blobbers hosting your allocation by checking them via Get Allocation Info command.

Replace Blobber

Sometimes, a blobber might be malfunctioning or faulty or the blobber might be slow because it is far from your geolocation, in such cases, you might have to replace the blobber with a new one.

Use add_blobber and remove_blobber flag with update allocation command to replace a blobber hosting an allocation.

Parameter
Description
Valid Values

--allocation

Provide Allocation ID for replacing blobber

string

--add_blobber

Provide new Blobber ID . Can be fetched using List blobbers.

string

--remove_blobber

Provide ID for the blobber which has to remove

string

Sample Command:

./zbox updateallocation --allocation $ALLOC --add_blobber 8d19a8fd7147279d1dfdadd7e3ceecaf91c63ad940dae78731e7a64b104441a6 --remove_blobber 06166f3dfd72a90cd0b51f4bd7520d4434552fc72880039b1ee1e8fe4b3cd7ea

Sample Response:

allocation updated successfully

Note: To find a blobber that can be replaced you should check the current set of blobbers hosting your allocation with Get Allocation Info command.

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

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.

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
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 :

Update Validator Settings

Use ./zbox validator-update to update a validator's configuration settings.

Parameter
Required
Description
default
Valid values

validator_id

yes

id of validator of which to update settings

string

num_delegates

no

update maximum number of delegates

int

max_stake

no

update maximum stake

float

min_stake

no

update minimum stake

float

service_charge

no

update service charge

float

Sample Command:

Update validator max stake

./zbox validator-update --validator_id  f82ab34a98406b8757f11513361752bab9cb679a5cb130b81a4e86cec50eefc3 --max_stake 7.5

Kill Blobber

./zbox kill-blobber command deactivates a blobber to avoid storage of data .Required parameters are

Parameter
Required
Description

--id

yes

Blobber Id to deactivate a specific blobber ,can be retrieved using List blobbers command.

--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

Kill Validator

./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
PreviousGet StartedNextUploading and Managing Files

Last updated