Creating & Managing Allocations

An allocation is reserved storage space on blobbers. The zbox CLI provides commands to create, update, transfer, forbid, cancel, finalize allocations, and manage blobber/validator settings.

You may see commands written as ./zbox or zbox.

• Use ./zbox if you are running the binary directly from the folder where it was built (e.g., after make install inside the repo).

• Use zbox if the binary has been installed into your system’s $PATH (e.g., /usr/local/bin), which lets you call it from anywhere.

Functionally, both are the same — the difference is whether your system can find the zbox command globally or only in the current directory.

---

1. Create New Allocation

The newallocation command reserves hard disk space on blobbers. Later, upload can be used to save files to the allocation.

newallocation has three modes:

• Cost mode (--cost) → Returns only the estimated cost.

• Free storage mode (--free_storage) → Uses a free storage marker JSON.

• Standard mode (default) → Creates an allocation with user-specified parameters.

Command

zbox newallocation [flags]

Parameters

Parameter	Description	Default	Values
--allocationFileName	Local file to store allocation info	allocation.txt	file path
--cost	Estimate cost only	–	flag
--data	Number of data shards (affects speed)	2	int
--parity	Number of parity shards (affects durability)	2	int (1 < p < 30)
--size	Reserved space (bytes)	2147483648	int
--lock*	Tokens locked in write pool	required	float
--free_storage	Free storage marker file	–	path
--owner	Owner’s ID (create for another user)	client	string
--owner_public_key	Owner’s public key	–	string
--read_price	Max read price	0–inf	range
--write_price	Max write price	0–inf	range
--usd	Show value in USD	–	flag
--third_party_extendable	Allow extensions by others	false	bool
--forbid_*	Forbid operations (upload, delete, update, move, copy, rename)	false	bool
--blobber_auth_tickets	Comma-separated auth tickets	–	strings
--preferred_blobbers	Comma-separated blobber IDs	auto	strings
--force	Force allocation even if insufficient blobbers	false	bool
--name	Allocation name	–	string

• --lock is required unless --free_storage is used.

Free Storage Marker Format

{
  "assigner": "my_corporation",
  "recipient": "f174cdda7e24aeac0288afc2e8d8b20eda06b18333efd447725581dc80552977",
  "free_tokens": 2.1,
  "timestamp": 2000000,
  "signature": "9edb86c8710d5e3ee4fde247c638fd6b81af67e7bb3f9d60700aec8e310c1f06"
}

Examples

Standard Allocation

./zbox newallocation --lock 0.5

Free Storage Allocation

./zbox newallocation --lock 0.5 --free_storage markers/my_marker.json

Response

Allocation created : d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac

---

2. Update Allocation

updateallocation modifies allocation settings.

Modes:

• Free storage update → Uses --free_storage marker.

• Standard update → Extends expiry, size, or adds/removes blobbers.

Command

zbox updateallocation --allocation <id> [flags]

Key Parameters

Parameter	Description
--allocation	Allocation ID (required)
--extend	Extend expiry (duration, e.g. 48h)
--size	Increase allocation size (bytes)
--lock	Add tokens to write pool
--add_blobber	Add blobber (requires --remove_blobber for swap)
--remove_blobber	Remove blobber
--third_party_extendable	Allow others to extend
--forbid_*	Forbid operations (upload, delete, etc.)

Examples

./zbox updateallocation --allocation <id> --expiry 48h --size 4096
./zbox updateallocation --allocation <id> --free_storage markers/my_marker.json

Response

Allocation updated with txId : fb84185dae620bbba8386286726f1efcd20d2516bcf1a448215434d87be3b30d

---

3. Transfer Allocation Ownership

Transfer allocation from current owner to another user.

Command

zbox transferallocation --allocation <id> --new_owner <id> --new_owner_key <pubkey>

Response

Transferred ownership of allocation : <id> to <new_owner>

4. Forbid Allocation Operations

Restrict operations using forbid flags with updateallocation.

Flag	Effect
--forbid_upload	Prevent file uploads
--forbid_delete	Prevent deletions
--forbid_update	Prevent updates
--forbid_move	Prevent moves
--forbid_copy	Prevent copies
--forbid_rename	Prevent renames

Example

./zbox updateallocation --allocation <id> --forbid_upload

---

5. Cancel Allocation

Immediately cancels allocation and returns tokens (except already distributed to blobbers).

Command

zbox alloc-cancel --allocation <id>

Response

Allocation canceled with txId : 501df5a8e2a6b8ebced1d1e7dc4ed17f653012dd49834801b4413786ec031cd2

---

6. Finalise Allocation

Finalises an expired allocation. Can be run by owner or blobber.

Command

zbox alloc-fini --allocation <id>

Response

Allocation finalized with txId : 2a6c031ced1d1e7dc4ed17801b4413786ecd2501df5ab8ebf653012dd498348e

---

7. Listing Allocations & Blobbers

List Allocations

zbox listallocations

List All Files in Allocation

zbox list-all --allocation <id>

List Blobbers

zbox ls-blobbers

Blobber Info

zbox bl-info --blobber_id <id>

---

8. Blobber & Validator Settings

Update Blobber Settings

zbox bl-update --blobber_id <id> --read_price 0.1

Update Validator Settings

zbox validator-update --validator_id <id> --service_charge 0.1

List Validators

zbox ls-validators

Validator Info

zbox validator-info --validator_id <id>

---

9. Shutdown / Kill Blobbers & Validators

Shutdown Blobber

zbox shutdown-blobber --id <id> --wallet <chain_owner_wallet>

Kill Blobber

zbox kill-blobber --id <id> --wallet <chain_owner_wallet>

Shutdown Validator

zbox shutdown-validator --id <id> --wallet <chain_owner_wallet>

Kill Validator

zbox kill-validator --id <id> --wallet <chain_owner_wallet>

---

10. Version

Get CLI & SDK version:

zbox version

Response

zbox....: v1.4.3
gosdk...: v1.8.14