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

PreviousInstallationNextUploading & Managing Files

Last updated