README ¶
zbox - a CLI for 0Chain dStorage
zbox is a command line interface (CLI) tool to understand the capabilities of 0Chain dStorage and prototype your app. The utility is built using 0Chain's goSDK library written in Go. Check out a video on how to use the CLI to create an allocation (storage volume) and upload, download, update, delete, and share files and folders on the 0Chain dStorage platform.
Getting Started
Installation Guides
How to install on Linux
How to install on Windows
Other Platform Builds
Use custom miner/sharder
As mentioned in build guides, a ./zcn folder is created to store configuration files for zboxcli. Here is a sample network config file
---
block_worker: https://beta.0chain.net
signature_scheme: bls0chain
min_submit: 50 # in percentage
min_confirmation: 50 # in percentage
confirmation_chain_length: 3
A blockWorker is used to connect to the network instead of giving network details directly, It will fetch the network details automatically from the blockWorker's network API. By default it will use the miner/sharder values which it will get using the block_worker_url/network
. In case you want to override those values and give custom miner/sharder to use, You have to create a network.yaml
in your ~/.zcn (config) folder and paste the miner/sharder values in below format.
miners:
- http://localhost:7071
- http://localhost:7072
- http://localhost:7073
sharders:
- http://localhost:7171
Note: This is helpful for the Mac OS users running local cluster and having trouble with docker internal IPs (block_worker return docker IPs in local)
Running zbox
When you run the zbox
command in terminal with no arguments, it will list all the available commands and the global flags.
Command | Description |
---|---|
add-collab | add collaborator for a file |
addcurator | Adds a curator to an allocation |
alloc-cancel | Cancel an allocation |
alloc-fini | Finalize an expired allocation |
bl-info | Get blobber info |
bl-update | Update blobber settings by its delegate_wallet owner |
commit | commit file changes to chain |
copy | copy an object(file/folder) to another folder on blobbers |
cp-info | Challenge pool information. |
delete | delete file from blobbers |
delete-collab | delete collaborator for a file |
download | download file from blobbers |
get | Gets the allocation info |
get-diff | Get difference of local and allocation root |
get-download-cost | Get downloading cost |
get-upload-cost | Get uploading cost |
getwallet | Get wallet information |
help | Help about any command |
list | list files from blobbers |
list-all | list all files from blobbers |
listallocations | List allocations for the client |
ls-blobbers | Show active blobbers in storage SC. |
meta | get meta data of files from blobbers |
move | move an object(file/folder) to another folder on blobbers |
newallocation | Creates a new allocation |
register | Registers the wallet with the blockchain |
rename | rename an object(file/folder) on blobbers |
rp-create | Create read pool if missing |
rp-info | Read pool information. |
rp-lock | Lock some tokens in read pool. |
rp-unlock | Unlock some expired tokens in a read pool. |
sc-config | Show storage SC configuration. |
share | share files from blobbers |
sign-data | Sign given data |
sp-info | Stake pool information. |
sp-lock | Lock tokens lacking in stake pool. |
sp-pay-interests | Pay interests not payed yet. |
sp-unlock | Unlock tokens in stake pool. |
sp-user-info | Stake pool information for a user. |
start-repair | start repair file to blobbers |
stats | stats for file from blobbers |
sync | Sync files to/from blobbers |
transferallocation | Transfer an allocation between owners |
update | update file to blobbers |
updateallocation | Updates allocation's expiry and size |
upload | upload file to blobbers |
version | Prints version information |
wp-info | Write pool information. |
wp-lock | Lock some tokens in write pool. |
wp-unlock | Unlock some expired tokens in a write pool. |
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 |
--verbose | Provides additional details as to what the particular 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 <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> |
Commands
Note in this document, we will only show the commands for particular functionalities, the response will vary depending on your usage and may not be provided in all places. To get a more descriptive view of all the zbox functionalities check zbox cli documentation at docs.0chain.net.
Register wallet
register
is used when needed to register a given wallet to the blockchain.
This could be because the blockchain network has been reset and you wished to register
the wallet at ~/.zcn/wallet.json
.
Sample command
./zbox register
Sample output
Wallet registered
Create new allocation
Command newallocation
reserves hard disk space on the blobbers. Later upload
can be used to save files to the blobber. newallocation
has three modes triggered
by the presence or absence of the cost
and free_storage
parameters.
cost
Convertsnewallocation
into a query that returns the cost of the allocation determined by the remaining parameters.free_storage
Creates an allocation using a free storage marker. All other parameters exceptcost
will be ignored. The allocation settings will be set automatically by0chain
, from preconfigured values.otherwise
Creates an allocation applying the settings indicated by the remaining parameters.- Use
owner
if you want to create and fund an allocation for someone else. If using this option then you need to provide the new owner's public key. Otherwise, the owner defaults to the client.
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 |
newallocation
Free storage newallocation
Free storage allocation
Entities can give free 0chain
storage in the form of markers. A marker takes the
form of a json file
{
"assigner": "my_corporation",
"recipient": "f174cdda7e24aeac0288afc2e8d8b20eda06b18333efd447725581dc80552977",
"free_tokens": 2.1,
"timestamp": 2000000,
"signature": "9edb86c8710d5e3ee4fde247c638fd6b81af67e7bb3f9d60700aec8e310c1f06"
}
assigner
A label for the entity providing the free storage.recipient
The marker has to be run by the recipient to be valid.free_tokens
The amount of free tokens. 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. All allocation settings, other thanlock
, will be set automatically by 0chain. Once created, an allocation funded by a free storage marker becomes identical to any other allocation; Its history forgotten.
./zbox newallocation --free_allocation markers/referal_marker.json
Allocation created : d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac
Example
To create a new allocation with default values,use newallocation
with a --lock
flag to add
some tokens to the write pool .On success a related write pool is created and the allocation
information is stored under $HOME/.zcn/allocation.txt
.
./zbox newallocation --lock 0.5
To use a free storage marker, you only need to provide the path to the marker file.
./zbox newallocation --lock 0.5 --free_storage markers/my_marker.json
Response:
Allocation created : d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac
Update allocation
updateallocation
updates allocation settings. It has two modes depending on
the presence of the free_storage
field.
free_storage
Uses a free storage marker to fund this allocation update; settings predefined by0chain
. See newallocation for further details.otherwise
Update an allocation applying the settings indicated by the remaining parameters.
If not a free_storage
update, then tokens will come from those locked. If there are
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 | |
* only required if free_storage not set. |
updateallocation
Free storage updateallocation
./zbox updateallocation --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac --expiry 48h --size 4096
./zbox updateallocation --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac --free_storage "markers/my_marker.json"
Output:
Allocation updated with txId : fb84185dae620bbba8386286726f1efcd20d2516bcf1a448215434d87be3b30d
You can see more txn details using above txID in block explorer here.
Cancel allocation
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.
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 |
alloc-cancel
Example
./zbox alloc-cancel --allocation <allocation_id>
Finalise allocation
alloc-fini
finalises an expired allocation. 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.
An allocation can be finalised by the owner or one of the allocation blobbers.
Parameter | Required | Description | Valid Values |
---|---|---|---|
allocation | yes | allocation id | string |
alloc-fini
Example
./zbox alloc-fini --allocation <allocation_id>
Add curator
addcurator
adds a curator to an allocation.
A curator can transfer ownership of an allocation. Each allocation
maintains a list of these curators.
Parameter | Required | Description | Valid Values |
---|---|---|---|
allocation | yes | allocation id | string |
curator | yes | id of new curator to add to allocation | string |
addcurator
./zbox addcurator --allocation fb84185dae620bbba8386286726f1efcd20d2516bcf1a448215434d87be3b30d --curator e49458a13f8a000b5959d03f8f7b6fa397b578643940ba50d3470c201d333429
e49458a13f8a000b5959d03f8f7b6fa397b578643940ba50d3470c201d333429 added as a curator to allocation fb84185dae620bbba8386286726f1efcd20d2516bcf1a448215434d87be3b30d
Transfer allocation ownership
transferallocation
changes the owner of an allocation. Only a curator,
previously added by an 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.
Parameter | Required | Description | Valid Values |
---|---|---|---|
allocation | yes | allocatino id | string |
new_owner | yes | id of the new owner | string |
new_owner_key | yes | public key of new owner | string |
transferallocation
./zbox trnasferallocation --allocation fb84185dae620bbba8386286726f1efcd20d2516bcf1a448215434d87be3b30d \
--new_owner 8b87739cd6c966c150a8a6e7b327435d4a581d9d9cc1d86a88c8a13ae1ad7a96
--new_owner_key a2df94e69954e51999f768aeca40bf0678e168fa9eb21ee5c82c32a9c25fb71fe9a340b726456d6e557f92854975ef04270291cdc1853e56000b0a6b48312d13
Output
transferred ownership of fb84185dae620bbba8386286726f1efcd20d2516bcf1a448215434d87be3b30d to 8b87739cd6c966c150a8a6e7b327435d4a581d9d9cc1d86a88c8a13ae1ad7a96
List blobbers
Use ls-blobbers
command to show active blobbers.
Parameter | Required | Description | Valid Values |
---|---|---|---|
all | no | shows active and non active blobbers | flag |
json | no | display result in .json format | flag |
ls-blobbers
Example
./zbox ls-blobbers
- id: 0ece681f6b00221c5567865b56040eaab23795a843ed629ce71fb340a5566ba3
url: http://five.devnet-0chain.net:31302
used / total capacity: 101.7 GiB / 1000.0 GiB
terms:
read_price: 0.01 tok / GB
write_price: 0.01 tok / GB / time_unit
min_lock_demand: 0.1
cct: 2m0s
max_offer_duration: 744h0m0s
- id: 788b1deced159f12d3810c61b4b8d381e80188c470e9798939f2e5036d964ffc
url: http://five.devnet-0chain.net:31301
used / total capacity: 102.7 GiB / 1000.0 GiB
terms:
read_price: 0.01 tok / GB
write_price: 0.01 tok / GB / time_unit
min_lock_demand: 0.1
cct: 2m0s
max_offer_duration: 744h0m0s
Detailed blobber information
Use bl-info
command to get detailed blobber information.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
blobber id | yes | blobber on which to get information | string | |
json | no | print result in json format | false | boolean |
bl-info
Example
./zbox bl-info --blobber_id f65af5d64000c7cd2883f4910eb69086f9d6e6635c744e62afcfab58b938ee25
Response:
id: f65af5d64000c7cd2883f4910eb69086f9d6e6635c744e62afcfab58b938ee25
url: http://zerominer.xyz:5051
capacity: 1.0 GiB
last_health_check: 2021-04-08 22:54:50 +0700 +07
capacity_used: 0 B
terms:
read_price: 0.01 tok / GB
write_price: 0.1 tok / GB
min_lock_demand: 10 %
max_offer_duration: 744h0m0s
cct: 2m0s
settings:
delegate_wallet: 8b87739cd6c966c150a8a6e7b327435d4a581d9d9cc1d86a88c8a13ae1ad7a96
min_stake: 1 tok
max_stake: 100 tok
num_delegates: 50
service_charge: 30 %
List all files
list-all
lists al the files stored with an allocation
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id, sender must be allocation owner | string |
./zbox list-all --allocation 4ebeb69feeaeb3cd308570321981d61beea55db65cbeba4ba3b75c173c0f141b
List owner's allocations
listallocations
provides a list of all allocations owned by the user.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
json | no | print output in json format | boolean |
listallocations
./zbox listallocations
ZED | CANCELED | R PRICE | W PRICE
+------------------------------------------------------------------+-----------+-------------------------------+------------+--------------+-----------+----------+----------+--------------+
4ebeb69feeaeb3cd308570321981d61beea55db65cbeba4ba3b75c173c0f141b | 104857600 | 2021-07-16 13:34:29 +0100 BST | 1 | 1 | false | false | 0.02 | 0.1999999998
Update blobber settings
Use ./zbox bl-update
to update a blobber's configuration settings. This updates the settings
on the blockchain not the blobber.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
blobber_id | yes | id of blobber of which to update settings | string | |
capacity | no | update blobber capacity | int | |
cct | no | update challenge completion time | duration | |
max_offer_duration | no | update max offer duration | duration | |
max_stake | no | update maximum stake | float | |
min_lock_demand | no | update minimum lock demand | float | |
min_stake | no | update minimum stake | float | |
num_delegates | no | update maximum number of delegates | int | |
read_price | no | update read price | float | |
service_charge | no | update service charge | float | |
write_price | no | update write price | float |
bl-update
Example
Update blobber read price
./zbox bl-update --blobber_id 0ece681f6b00221c5567865b56040eaab23795a843ed629ce71fb340a5566ba3 --read_price 0.1
Upload
Use upload
command to upload file(s).
- upload a local file
- download segment files from remote live feed, and upload them
- start live streaming from local devices, encode it into segment files with
ffmpeg
, and upload them.
The user must be the owner of the allocation.You can request the file be encrypted before upload, and can send thumbnails with the file.
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id, sender must be allocation owner | string | |
commit | no | save metadata to blockchain | false | boolean |
encrypt | no | encrypt file before upload | false | boolean |
localpath | yes | local path of the file to upload | file path | |
remotepath | yes | remote path to upload file to, use to access file later | string | |
thumbnailpath | no | local path of thumbnaSil | file path | |
chunksize | no | chunk size | 65536 | int |
delay | no | set segment duration to seconds. only works with --live and --sync. | 5 | int |
sync | no | enable SyncUpload from remote live feed. disabled it by default. | false | boolean |
feed | no | set remote live feed to url. only works with --sync. | false | url |
downloader-args | no | pass args to youtube-dl to download video. default is "-q -f best". only works with --sync. | -q -f best | youtube-dl |
ffmpeg-args | no | pass args to ffmpeg to build segments. only works with --sync. | -loglevel warning | ffmpeg |
live | no | enable LiveUpload from local devices. disabled by default. | false | boolean |
upload
Example
Upload file with no encryption
./zbox upload --localpath /absolute-path-to-local-file/hello.txt --remotepath /myfiles/hello.txt --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac
Response:
12390 / 12390 [================================================================================] 100.00% 3s
Status completed callback. Type = application/octet-stream. Name = hello.txt
Upload file with encryption
Use upload command with optional encrypt parameter to upload a file in encrypted format. This can be downloaded as normal from same wallet/allocation or utilize Proxy Re-Encryption facility (see download command).
./zbox upload --encrypt --localpath <absolute path to file>/sensitivedata.txt --remotepath /myfiles/sensitivedata.txt --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac
Response:
12390 / 12390 [================================================================================] 100.00% 3s
Status completed callback. Type = application/octet-stream. Name = sensitivedata.txt
Download segment files from remote live feed, re-encode and upload
Use upload --sync
command to automatically download segment files from remove live feed with --downloader-args "-f 22"
, encode them into new segment files with --delay
and --ffmpeg-args
, and upload. please use youtube-dl -F https://www.youtube.com/watch?v=pC5mGB5enkw
to list formats of video (see below).
[youtube] pC5mGB5enkw: Downloading webpage
[info] Available formats for pC5mGB5enkw:
format code extension resolution note
249 webm audio only tiny 44k , webm_dash container, opus @ 44k (48000Hz), 95.21MiB
250 webm audio only tiny 59k , webm_dash container, opus @ 59k (48000Hz), 127.05MiB
251 webm audio only tiny 123k , webm_dash container, opus @123k (48000Hz), 264.98MiB
140 m4a audio only tiny 129k , m4a_dash container, mp4a.40.2@129k (44100Hz), 277.82MiB
278 webm 256x136 144p 87k , webm_dash container, vp9@ 87k, 30fps, video only, 188.78MiB
160 mp4 256x136 144p 118k , mp4_dash container, avc1.4d400c@ 118k, 30fps, video only, 253.62MiB
242 webm 426x224 240p 190k , webm_dash container, vp9@ 190k, 30fps, video only, 409.20MiB
133 mp4 426x224 240p 252k , mp4_dash container, avc1.4d400d@ 252k, 30fps, video only, 541.15MiB
243 webm 640x338 360p 326k , webm_dash container, vp9@ 326k, 30fps, video only, 701.53MiB
134 mp4 640x338 360p 576k , mp4_dash container, avc1.4d401e@ 576k, 30fps, video only, 1.21GiB
244 webm 854x450 480p 649k , webm_dash container, vp9@ 649k, 30fps, video only, 1.36GiB
135 mp4 854x450 480p 1028k , mp4_dash container, avc1.4d401f@1028k, 30fps, video only, 2.16GiB
247 webm 1280x676 720p 1320k , webm_dash container, vp9@1320k, 30fps, video only, 2.77GiB
136 mp4 1280x676 720p 1988k , mp4_dash container, avc1.64001f@1988k, 30fps, video only, 4.17GiB
248 webm 1920x1012 1080p 2527k , webm_dash container, vp9@2527k, 30fps, video only, 5.30GiB
137 mp4 1920x1012 1080p 4125k , mp4_dash container, avc1.640028@4125k, 30fps, video only, 8.64GiB
271 webm 2560x1350 1440p 7083k , webm_dash container, vp9@7083k, 30fps, video only, 14.84GiB
313 webm 3840x2026 2160p 13670k , webm_dash container, vp9@13670k, 30fps, video only, 28.65GiB
18 mp4 640x338 360p 738k , avc1.42001E, 30fps, mp4a.40.2 (44100Hz), 1.55GiB
22 mp4 1280x676 720p 2117k , avc1.64001F, 30fps, mp4a.40.2 (44100Hz) (best)
--downloader-args "-f 22"
dowloads video with 22 mp4 1280x676 720p 2117k , avc1.64001F, 30fps, mp4a.40.2 (44100Hz) (best)
./zbox upload --sync --localpath <absolute path to file>/tvshow.m3u8 --remotepath /videos/tvsho --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac --delay 10 --chunksize 655360 --downloader-args "-f 22" --feed https://www.youtube.com/watch?v=pC5mGB5enkw
Capture streaming from local devices, encode with ffmpeg, and upload
Use upload --live
to capture video and audio streaming form local devices, and upload
./zbox upload --live --localpath <absolute path to file>/streaming.m3u8 --remotepath /videos/streaming --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac --delay 10 --chunksize 655360
Download
Use download
command to download your own or a shared file.
owner
The owner of the allocation can always download files, in this case the owner pays for the download.collaborator
A collaborator can download files, the owner pays. To add collaborators to an allocation, use add-collab.authticket
To download a file usingauthticket
, you must have previous be given an auth ticket using the share command. Use rx_pay to indicate who pays,rx_pay = true
you pay,rx_pay = false
the allocation owner pays. Usestartblock
andendblock
to only download part of the file.
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
authticket | no | auth ticked if not owner of the allocation, use share to get auth ticket | string | |
blockspermarker | no | download multiple blocks per marker | 10 | int |
commit | no | save metadata to blockchain | false | boolean |
endblock | no | download until specified block number | int | |
localpath | yes | local path to which to download the file to | file path | |
remotepath | yes | remote path to which the file was uploaded | string | |
rx_pay | no | authticket must be valid, true = sender pays, false = allocation owner pays |
false | boolean |
startblock | no | start download from specified block | int | |
thumbail | no | only download the thumbnail | false | boolean |
live | no | start m3u8 downloader,and automatically generate media playlist(m3u8) on --localpath | false | boolean |
delay | no | pass segment duration to generate media playlist(m3u8). only works with --live. default duration is 5s. | 5 | int |
download
Example
./zbox download --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 --remotepath /myfiles/horse.jpeg --localpath ../horse.jpeg
Response:
4 / 4 [=======================================================================] 100.00% 3s
Status completed callback. Type = application/octet-stream. Name = horse.jpeg
Note: You can download by using only 1 on the below combination:
--remotepath
,--allocation
--authticket
Downloaded file will be in the location specified by the localpath
argument.
Update
Use update
command to update content of an existing file in the remote path.
Like upload command. Only the owner of the allocation or a collaborator
can update a file. To add collaborators to an allocation, use
add-collab.
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
encrypt | no | encrypt file before upload | false | boolean |
localpath | yes | local file to upload | file path | |
remotepath | yes | remote file to upload | string | |
thumbnailpath | no | local fumbnail file to upload | file path | |
commit | no | save meta data to blockchain | false | boolean |
chunksize | no | chunk size | 65536 | int |
update
Delete
Use delete
command to delete your file on the allocation. Only the owner
of the application can delete a file.
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
remotepath | yes | remote path of file to delete | string | |
commit | no | save meta data to blockchain | false | boolean |
delete
Example
./zbox delete --allocation 3c0d32560ea18d9d0d76808216a9c634flist661979d29ba59cc8dafccb3e5b95341 --remotepath /myfiles/horse.jpeg
Response:
/myfiles/horse.jpeg deleted
File successfully deleted (Can be verified using list)
Share
Use share command to generate an authtoken that provides authorization to the holder to the specified file on the remotepath.
- --allocation string Allocation ID
- --clientid string ClientID of the user to share with. Leave blank for public share
- --encryptionpublickey string Encryption public key of the client you want to share with (from getwallet command )
- --remotepath string Remote path to share
- --expiration-seconds number The seconds after which the ticket will expire(defaults to number of seconds in 90 days if option not provided)
auth ticket
can be used with download, commit and list,
meta and get_download_cost, but only for files in
the pre-defined remote path.
Parameter | Required | Description | Valid values |
---|---|---|---|
allocation | yes | allocation id | string |
clientid | no | id of user to share file with, leave blank for public share | string |
encryptionpublickey | no | public key of the client to share file with, required if clientId | string |
expiration-seconds | no | seconds before auth ticket expires |
int |
remotepath | yes | remote path of file to share | string |
revoke | no | revoke share for remote path | flag |
share
Example
Public share
./zbox share --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 --remotepath /myfiles/hello.txt
Response:
Auth token eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3ZTExOTQwNmQ4ODg3ZDAyOGIxNDE0YWNmZTQ3ZTg4MDhmNWIzZjk4Njk2OTk4Nzg3YTIwNTVhN2VkYjk3YWYiLCJhbGxvY2F0aW9uX2lkIjoiODlkYjBjZDI5NjE4NWRkOTg2YmEzY2I0ZDBlODE0OTE3NmUxNmIyZGIyMWEwZTVjMDZlMTBmZjBiM2YxNGE3NyIsImZpbGVfcGF0aF9oYXNoIjoiM2NhNzIyNTQwZTY1M2Y3NTQ1NjI5ZjBkYzE5ZGY2ODk5ZTI0MDRjNDI4ZDRiMWZlMmM0NjI3ZGQ3MWY3ZmQ2NCIsImFjdHVhbF9maWxlX2hhc2giOiIyYmM5NWE5Zjg0NDlkZDEyNjFmNmJkNTg3ZjY3ZTA2OWUxMWFhMGJiIiwiZmlsZV9uYW1lIjoidGVzdC5wZGYiLCJyZWZlcmVuY2VfdHlwZSI6ImYiLCJleHBpcmF0aW9uIjoxNjM1ODQ5MzczLCJ0aW1lc3RhbXAiOjE2MjgwNzMzNzMsInJlX2VuY3J5cHRpb25fa2V5IjoiIiwiZW5jcnlwdGVkIjpmYWxzZSwic2lnbmF0dXJlIjoiZDRiOTM4ZTE0MDk0ZmZkOGFiMDcwOWFmN2QyMDAyZTdlMGFmNmU3MWJlNGFmMmRjNmUxMGYxZWJmZTUwOTMxOSJ9
Auth token decoded
{"client_id":"","owner_id":"17e119406d8887d028b1414acfe47e8808f5b3f98696998787a2055a7edb97af","allocation_id":"89db0cd296185dd986ba3cb4d0e8149176e16b2db21a0e5c06e10ff0b3f14a77","file_path_hash":"3ca722540e653f7545629f0dc19df6899e2404c428d4b1fe2c4627dd71f7fd64","actual_file_hash":"2bc95a9f8449dd1261f6bd587f67e069e11aa0bb","file_name":"test.pdf","reference_type":"f","expiration":1635849373,"timestamp":1628073373,"re_encryption_key":"","encrypted":false,"signature":"d4b938e14094ffd8ab0709af7d2002e7e0af6e71be4af2dc6e10f1ebfe509319"}
Encrypted share
Upload file with --encrypted tag.
Get encryptionpublickey first, by calling from user you sharing with:
./zbox getwallet
Response:
PUBLIC KEY | CLIENTID | ENCRYPTION PUBLIC KEY
-----------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------
19cd2396df9b8b77358a1110492ff65cbb5b55cae06b8bd204e0969b2454851ca620ae74aebe9ed641166be3bca056a1855610f6154f4f4435a29565a2111282 | b734ef935e2a02892b2fa31e3488b360ef300d3b0b32c03834cea3a83e2453f0 | 1JuT4AbQnmIaOMTuWn07t98xQRsSqXAxZYfwCI1yQLM=
You have to pickup ENCRYPTION PUBLIC KEY
Use clientid of the user to share with. encryptionpublickey - key from command above.
./zbox share --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 --remotepath /myfiles/hello.txt --clientid b6de562b57a0b593d0480624f79a55ed46dba544404595bee0273144e01034ae --encryptionpublickey 1JuT4AbQnmIaOMTuWn07t98xQRsSqXAxZYfwCI1yQLM=
Response:
Auth token eyJjbGllbnRfaWQiOiIwMGZmODhkY2IxNjQ2Y2RlZjA2OWE4MGE0MGQwMWNlOTYyMmQ3ZmUzYmQ0ZWNjMzIzYTcwZTdkNmVkMWE2YjY3Iiwib3duZXJfaWQiOiIxN2UxMTk0MDZkODg4N2QwMjhiMTQxNGFjZmU0N2U4ODA4ZjViM2Y5ODY5Njk5ODc4N2EyMDU1YTdlZGI5N2FmIiwiYWxsb2NhdGlvbl9pZCI6Ijg5ZGIwY2QyOTYxODVkZDk4NmJhM2NiNGQwZTgxNDkxNzZlMTZiMmRiMjFhMGU1YzA2ZTEwZmYwYjNmMTRhNzciLCJmaWxlX3BhdGhfaGFzaCI6IjM2Mjk0MGMwMTZlOWZlZTQ4ZmI5MTA0OGI4MzJjOGFlNWQ2MGUyYzUzMmQ1OGNlYzdmNGM0YjBmZTRkZjM2MzYiLCJhY3R1YWxfZmlsZV9oYXNoIjoiMmJjOTVhOWY4NDQ5ZGQxMjYxZjZiZDU4N2Y2N2UwNjllMTFhYTBiYiIsImZpbGVfbmFtZSI6InRlc3QyLnBkZiIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2MzU4NDk4NDMsInRpbWVzdGFtcCI6MTYyODA3Mzg0MywicmVfZW5jcnlwdGlvbl9rZXkiOiIiLCJlbmNyeXB0ZWQiOnRydWUsInNpZ25hdHVyZSI6IjNlNGMwOTAwMzAwN2M5NzUzZjFiNGIwODExMWM4OGRlY2JmZjU2MDRmNTIwZDZjMmYyMTdhMzUyZTFkMmE0MTEifQ==
Auth token decoded
{"client_id":"00ff88dcb1646cdef069a80a40d01ce9622d7fe3bd4ecc323a70e7d6ed1a6b67","owner_id":"17e119406d8887d028b1414acfe47e8808f5b3f98696998787a2055a7edb97af","allocation_id":"89db0cd296185dd986ba3cb4d0e8149176e16b2db21a0e5c06e10ff0b3f14a77","file_path_hash":"362940c016e9fee48fb91048b832c8ae5d60e2c532d58cec7f4c4b0fe4df3636","actual_file_hash":"2bc95a9f8449dd1261f6bd587f67e069e11aa0bb","file_name":"test2.pdf","reference_type":"f","expiration":1635849843,"timestamp":1628073843,"re_encryption_key":"","encrypted":true,"signature":"3e4c09003007c9753f1b4b08111c88decbff5604f520d6c2f217a352e1d2a411"}
Response contains an auth ticket- an encrypted string that can be shared.
Directory share
Follow up steps above to get encryptionpublickey
Upload multiple files to directory with zbox upload /folder1/file1.z ...
./zbox share --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 --remotepath /folder1 --clientid b6de562b57a0b593d0480624f79a55ed46dba544404595bee0273144e01034ae --encryptionpublickey 1JuT4AbQnmIaOMTuWn07t98xQRsSqXAxZYfwCI1yQLM=
Response:
Encoded
eyJjbGllbnRfaWQiOiJiNzM0ZWY5MzVlMmEwMjg5MmIyZmEzMWUzNDg4YjM2MGVmMzAwZDNiMGIzMmMwMzgzNGNlYTNhODNlMjQ1M2YwIiwib3duZXJfaWQiOiI2MzlmMjcxZmU1MTFjZDE4ODBjMmE0ZDhlYTRhNGYyNDBmYWYzMzY1YzYxYjY1YjQyNWZhYjVlMDIzMTcxM2MzIiwiYWxsb2NhdGlvbl9pZCI6IjkzN2FkNjlmYjIwZGMxMTFiY2ZkMDFkZTQyYzc5MmEwYzJiNDQxZGUzZDNjZjRjZGIzZjI1YzIxYzFhYjRiN2IiLCJmaWxlX3BhdGhfaGFzaCI6ImFkMThmMzg1Y2I2MWM4MTNjMzE0NDU2OTM0NWYxYzQ2ODE1ODljNzM0N2JkNzI4NjkyZTg1ZjFiNzM4NmI2OWQiLCJhY3R1YWxfZmlsZV9oYXNoIjoiIiwiZmlsZV9uYW1lIjoiZm9sZGVyMSIsInJlZmVyZW5jZV90eXBlIjoiZCIsImV4cGlyYXRpb24iOjE2MzYyODgwNDMsInRpbWVzdGFtcCI6MTYyODUxMjA0MywicmVfZW5jcnlwdGlvbl9rZXkiOiIiLCJlbmNyeXB0ZWQiOnRydWUsInNpZ25hdHVyZSI6ImNiYTZlMjA2OTBjOGZjZTk5YmFjZTMzYjFjMGY3ODQ5ZDE4YmJlMTdhODkyNjczODg1MjI2MDc3MGQzNzgzMGQifQ==
Decoded
{"client_id":"b734ef935e2a02892b2fa31e3488b360ef300d3b0b32c03834cea3a83e2453f0","owner_id":"639f271fe511cd1880c2a4d8ea4a4f240faf3365c61b65b425fab5e0231713c3","allocation_id":"937ad69fb20dc111bcfd01de42c792a0c2b441de3d3cf4cdb3f25c21c1ab4b7b","file_path_hash":"ad18f385cb61c813c3144569345f1c4681589c7347bd728692e85f1b7386b69d","actual_file_hash":"","file_name":"folder1","reference_type":"d","expiration":1636288043,"timestamp":1628512043,"re_encryption_key":"","encrypted":true,"signature":"cba6e20690c8fce99bace33b1c0f7849d18bbe17a8926738852260770d37830d"}
Make sure "reference_type":"d" is "d" (directory)
Now you able to download files inside this directory with same auth_ticket. To download it just point to excact file location in --remotepath param:
zbox download --allocation 76ad9fa86f9b6685880553588a250586806ba5d7d20fc229d6905998be55d64a --localpath ~/file1.z --authticket $auth --remotepath /folder1/file1.z
This method works for both: encrypted and non-encrypted files.
share-encrypted revoke
This will cancel the share for particular buyer that was performed by the seller using zbox share. Works only for files with --encrypted tag.
Use clientid of the user that was share the remotepath. Required parameters are allocation, remotepath and clientid.
Command
./zbox share --revoke --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 --remotepath /myfiles/hello.txt --clientid d52d82133177ec18505145e784bc87a0fb811d7ac82aa84ae6b013f96b93cfaa
Response
Returns status message showing whether the operation was successful or not.
List
Use list
command to list files in given remote path of the dStorage. An auth ticket should be provided when
not sent by the allocation's owner. Using an auth ticket requires a lookuphash
to indicate the path for which to list
contents.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
authticket | no | auth ticked if not owner of the allocation, use share to get auth ticket | sting | |
json | no | output the response in json format | false | boolean |
lookuphash | no | hash of object to list, use with auth ticket. | string | |
remotepath | no | remote path of objects to list, for auth ticket use lookuphash instead | string |
list
Example
./zbox list --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --remotepath /
Response:
auth ticket :eyJjbGllbnRfaWQiOiJiNmRlNTYyYjU3YTBiNTkzZDA0ODA2MjRmNzlhNTVlZDQ2ZGJhNTQ0NDA0NTk1YmVlMDI3MzE0NGUwMTAzNGFlIiwib3duZXJfaWQiOiJiNmRlNTYyYjU3YTBiNTkzZDA0ODA2MjRmNzlhNTVlZDQ2ZGJhNTQ0NDA0NTk1YmVlMDI3MzE0NGUwMTAzNGFlIiwiYWxsb2NhdGlvbl9pZCI6Ijg2OTViOWU3Zjk4NmQ0YTQ0N2I2NGRlMDIwYmE4NmY1M2IzYjVlMmM0NDJhYmNlYjZjZDY1NzQyNzAyMDY3ZGMiLCJmaWxlX3BhdGhfaGFzaCI6IjIwZGM3OThiMDRlYmFiMzAxNTgxN2M4NWQyMmFlYTY0YTUyMzA1YmFkNmY3NDQ5YWNkMzgyOGM4ZDcwYzc2YTMiLCJmaWxlX25hbWUiOiIxLnR4dCIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2MjY0MjA1NzQsInRpbWVzdGFtcCI6MTYxODY0NDU3NCwicmVfZW5jcnlwdGlvbl9rZXkiOiJ7XCJyMVwiOlwiOUpnci9aVDh6VnpyME1BcWFidlczdnhoWEZoVkdMSGpzcVZtVUQ1QTJEOD1cIixcInIyXCI6XCIrVEk2Z1pST3JCR3ZURG9BNFlicmNWNXpoSjJ4a0I4VU5SNTlRckwrNUhZPVwiLFwicjNcIjpcInhySjR3bENuMWhqK2Q3RXU5TXNJRzVhNnEzRXVzSlZ4a2N6YXN1K0VqQW89XCJ9Iiwic2lnbmF0dXJlIjoiZTk3NTYyOTAyODU4OTBhY2QwYTcyMzljNTFhZjc0YThmNjU2OTFjOTUwMzRjOWM0ZDJlMTFkMTQ0MTk0NmExYSJ9
Response will be a list with information for each file/folder in the given path. The information includes lookuphash which is require for download via authticket.
Copy
Use copy
command to copy file to another folder path in dStorage.
Only the owner of the allocation can copy an object.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
commit | no | save metadata to blockchain | false | boolean |
remotepath | yes | remote path of object to copy | string | |
destpath | yes | destination, an existing directory to copy object | string |
copy
Example
./zbox copy --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac --remotepath
Response:
/file.txt --destpath /existingFolder
/file.txt copied
Move
Use move
command to move file to another remote folder path on dStorage.
Only the owner of the allocation can copy an object.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
commit | no | save metadata to blockchain | false | boolean |
remotepath | yes | remote path of object to copy | string | |
destpath | yes | destination, an existing directory to copy object | string |
move
Example
./zbox move --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac --remotepath
Response:
/file.txt --destpath /existingFolder
/file.txt moved
Sync
sync
command syncs all files from the local folder recursively to the remote.
Only the allocation's owner can successfully run sync
.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
commit | no | commet metadata to blockchain | false | boolean |
encryptpath | no | local directory path to be uploaded as encrypted | false | boolean |
exludepath | no | paths to exclude from sync | string array | |
localchache | no | local chache of remote snapshot. Used for comparsion with remote. After sync will be updated. | string | |
localpath | yes | local directory to which to sync | file path | |
uploadonly | no | only upload and update files | false | boolean |
chunksize | no | chunk size | 65536 | int |
sync
Example
./zbox sync --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --localpath /home/dung/Desktop/alloc --localcache /home/dung/Desktop/localcache.json
Response:
OPERATION | PATH
+-----------+----------------+
Download | /1.txt
Download | /afolder/1.txt
Download | /d2.txt
4 / 4 [===========================================================================] 100.00% 0s
Status completed callback. Type = application/octet-stream. Name = 1.txt
4 / 4 [===========================================================================] 100.00% 0s
Status completed callback. Type = application/octet-stream. Name = 1.txt
7 / 7 [===========================================================================] 100.00% 0s
Status completed callback. Type = application/octet-stream. Name = d2.txt
Sync Complete
Local cache saved.
It will sync your localpath with the remote and do all the required CRUD operations.
Get differences
get-diff
returns the differences between local files, and the files stored
with the allocation.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
excludepath | no | remote folder paths to exclude during syncing | string array | |
localcache | no | local chache of remote snapshot | string | |
localpath | yes | local director to sync | string |
Get wallet
Use getwallet
command to get additional wallet information including Encryption
Public Key,Client ID which are required for Private File Sharing.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
json | no | print response in json format | false | boolean |
Example
./zbox getwallet
Response:
PUBLIC KEY | CLIENTID | ENCRYPTION PUBLIC KEY
+----------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------------------------------------------+
3e7fa2dd6b924adfdf69e36cc61cb5d9012226dac619250ce5fc37eae25a05118008944d1727221b6d14b0998c5813acd13066040976598c5366e86519377001 | b6de562b57a0b593d0480624f79a55ed46dba544404595bee0273144e01034ae | 1JuT4AbQnmIaOMTuWn07t98xQRsSqXAxZYfwCI1yQLM=
Response will give details for current selected wallet (or wallet file specified by optional --wallet parameter)
Get
Use get
command to get the information about the allocation such as total size , used size, number of challenges
and challenges passed/failed/open/redeemed.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
json | no | print response in json format | false | boolean |
get
Example
./zbox get --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc
Response:
allocation:
id: 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc
tx: 026c9d331e9c93aee4f3247507c20bdd4b7429bd81d27845bfab83f9c9c082e6 (latest create/update allocation transaction hash)
data_shards: 4
parity_shards: 2
size: 6.0 GiB
expiration_date: 2021-05-24 00:27:23 +0700 +07
blobbers:
- blobber_id: dea18e3f3c308666cb489877b9b2c7e2babf797d8b8c322fa9d074105787a9e9
base URL: http://five.devnet-0chain.net:31304
size: 1.0 GiB
min_lock_demand: 0.0012333333
spent: 0.0000244839 (moved to challenge pool or to the blobber)
penalty: 0 (blobber stake slash)
read_reward: 0.000024414
returned: 0.0000000233 (on challenge failed)
challenge_reward: 0 (on challenge passed)
final_reward: 0 (if finalized)
terms: (allocation related terms)
read_price: 0.0099999999 tok / GB (by 64KB chunks)
write_price: 0.0099999999 tok / GB
min_lock_demand: 10 %
max_offer_duration: 744h0m0s
challenge_completion_time: 2m0s
Get metadata
Use meta
command to get metadata for a given remote file. Use must either be the
owner of the allocation on have an auth ticket or be a collaborator.
Use share to create an auth ticket for someone or add-collab
to add a user as a collaborator. To indicate the object use remotepath
or
lookuphash
with an auth ticket.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
authticket | no | auth ticked if not owner of the allocation | string | |
json | no | print result in json format | false | boolean |
lookuphash | no | hash of object, use with auth ticket | string | |
remotepath | no | remote path of objecte, do not use with authticket | string |
meta
Without any authticket
./zbox meta --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --remotepath /1.txt
Response:
TYPE | NAME | PATH | LOOKUP HASH | SIZE | MIME TYPE | HASH
+------+-------+--------+------------------------------------------------------------------+------+--------------------------+------------------------------------------+
f | 1.txt | /1.txt | 20dc798b04ebab3015817c85d22aea64a52305bad6f7449acd3828c8d70c76a3 | 4 | application/octet-stream | 03cfd743661f07975fa2f1220c5194cbaff48451
**With authticket **
./zbox meta --lookuphash 20dc798b04ebab3015817c85d22aea64a52305bad6f7449acd3828c8d70c76a3 --authticket eyJjbGllbnRfaWQiOiJiNmRlNTYyYjU3YTBiNTkzZDA0ODA2MjRmNzlhNTVlZDQ2ZGJhNTQ0NDA0NTk1YmVlMDI3MzE0NGUwMTAzNGFlIiwib3duZXJfaWQiOiJiNmRlNTYyYjU3YTBiNTkzZDA0ODA2MjRmNzlhNTVlZDQ2ZGJhNTQ0NDA0NTk1YmVlMDI3MzE0NGUwMTAzNGFlIiwiYWxsb2NhdGlvbl9pZCI6Ijg2OTViOWU3Zjk4NmQ0YTQ0N2I2NGRlMDIwYmE4NmY1M2IzYjVlMmM0NDJhYmNlYjZjZDY1NzQyNzAyMDY3ZGMiLCJmaWxlX3BhdGhfaGFzaCI6IjIwZGM3OThiMDRlYmFiMzAxNTgxN2M4NWQyMmFlYTY0YTUyMzA1YmFkNmY3NDQ5YWNkMzgyOGM4ZDcwYzc2YTMiLCJmaWxlX25hbWUiOiIxLnR4dCIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2MjY0MjA1NzQsInRpbWVzdGFtcCI6MTYxODY0NDU3NCwicmVfZW5jcnlwdGlvbl9rZXkiOiJ7XCJyMVwiOlwiOUpnci9aVDh6VnpyME1BcWFidlczdnhoWEZoVkdMSGpzcVZtVUQ1QTJEOD1cIixcInIyXCI6XCIrVEk2Z1pST3JCR3ZURG9BNFlicmNWNXpoSjJ4a0I4VU5SNTlRckwrNUhZPVwiLFwicjNcIjpcInhySjR3bENuMWhqK2Q3RXU5TXNJRzVhNnEzRXVzSlZ4a2N6YXN1K0VqQW89XCJ9Iiwic2lnbmF0dXJlIjoiZTk3NTYyOTAyODU4OTBhY2QwYTcyMzljNTFhZjc0YThmNjU2OTFjOTUwMzRjOWM0ZDJlMTFkMTQ0MTk0NmExYSJ9
Response:
TYPE | NAME | LOOKUP HASH | SIZE | MIME TYPE | HASH
+------+-------+------------------------------------------------------------------+------+--------------------------+------------------------------------------+
f | 1.txt | 20dc798b04ebab3015817c85d22aea64a52305bad6f7449acd3828c8d70c76a3 | 4 | application/octet-stream | 03cfd743661f07975fa2f1220c5194cbaff48451
Response will be metadata for the given filepath/lookuphash (if using authTicket)
Rename
rename
command renames a file existing already on dStorage. Only the
allocation's owner can rename a file.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
commit | no | save metadata to blockchain | false | boolean |
destname | yes | new neame of the object | string | |
remotepath | yes | remote path of object, do not use with authticket | string |
rename
Example
./zbox rename --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --remotepath /1.txt --destname x.txt
Response:
/1.txt renamed
Stats
stats
command gets upload, download and challenge statistics for a file.
Only the owner can get a files stats.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
json | no | print result in json format | false | boolean |
remotepath | yes | file of which to get stats | string |
stats
Example
./zbox stats --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --remotepath /1.txt
Response:
BLOBBER | NAME | PATH | SIZE | UPLOADS | BLOCK DOWNLOADS | CHALLENGES | BLOCKCHAIN AWARE
+------------------------------------------------------------------+-------+--------+------+---------+-----------------+------------+------------------+
9c14598d5d39cb27177add6efabdadfb0a0478abe5d471ffe9080751dc89321c | 1.txt | /1.txt | 2065 | 3 | 1 | 0 | true
dea18e3f3c308666cb489877b9b2c7e2babf797d8b8c322fa9d074105787a9e9 | 1.txt | /1.txt | 2065 | 3 | 1 | 0 | true
0ece681f6b00221c5567865b56040eaab23795a843ed629ce71fb340a5566ba3 | 1.txt | /1.txt | 2065 | 3 | 1 | 0 | true
788b1deced159f12d3810c61b4b8d381e80188c470e9798939f2e5036d964ffc | 1.txt | /1.txt | 2065 | 3 | 1 | 0 | true
78a1a9db859cded21a5120a5bf808e97202a1fd7f94e51d2fd174edbdc4d7291 | 1.txt | /1.txt | 2065 | 3 | 1 | 0 | true
876b4cd610eb1aac63c53cdfd4d3a0ac91d94f2d6b858bb195f72b6dc0f33b55 | 1.txt | /1.txt | 2065 | 3 | 1 | 0 | true
Repair
Use start-repair
command to repair a file on dStorage.
\
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
repairpath | yes | remote path to repair | string | |
rootpath | yes | file path for local files | string |
start-repair
Example
./zbox start-repair --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --repairpath / --rootpath /home/dung/Desktop/alloc
Response:
Repair file completed, Total files repaired: 0
Add collaborator
Use add-collab
command to add a collaborator for a file on dStorage.
Collaborators can perform read actions on the collaboration file, with the owner paying.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
collabid | yes | id of collaberator | string | |
remotepath | yes | file on which to collaberate | string |
add-collab
Example
./zbox add-collab --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --remotepath /1.txt --collabid d477d12134c2d7ba5ab71ac8ad37f244224695ef3215be990c3215d531c5a329
Response will be a confirmation that collaborator is added on all blobbers for the given file .
Collaborator d477d12134c2d7ba5ab71ac8ad37f244224695ef3215be990c3215d531c5a329 added successfully for the file /1.txt
You can check all collaborators for a file in metadata json response.
Delete collaborator
Use command delete-collab to remove a collaborator for a file
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
collabid | yes | id of collaberator | string | |
remotepath | yes | file on which to collaberate | string |
delete-collab
Example
./zbox delete-collab --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc --remotepath /1.txt --collabid d477d12134c2d7ba5ab71ac8ad37f244224695ef3215be990c3215d531c5a329
Response will be a confirmation that collaborator is removed on all blobbers for the given file.
Collaborator d477d12134c2d7ba5ab71ac8ad37f244224695ef3215be990c3215d531c5a329 removed successfully for the file /1.txt
Challenge pool information
Use cp-info
command to get the challenge pool brief information.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
json | no | print result in json format | false | boolean |
cp-info
Example
./zbox cp-info --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc
Response:
POOL ID: 6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d7:challengepool:8695b9e7f986d4a447b64de020ba86f53b3b5e2c442abceb6cd65742702067dc
BALANCE | START | EXPIRE | FINIALIZED
+--------------+-------------------------------+-------------------------------+------------+
0.0000002796 | 2021-04-17 00:27:23 +0700 +07 | 2021-05-24 00:29:23 +0700 +07 | false
Balance is the current challenge pool balance. Start,Expire time and the finalization are allocations related.
Create read pool
Use rp-create
to create a read pool, rp-create
has no parameters.
rp-create
./zbox rp-create
Read pool info
Use rp-info
to get read pool information.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | no | allocation id | string | |
json | no | print result in json format | false | boolean |
rp-info
./zbox rp-info
Lock tokens into read pool
Lock some tokens in read pool associated with an allocation.
- Uses two different formats, you can either define a specific blobber to lock all tokens, or spread across all the allocations blobbers automatically.
- If the user does not have a pre-existing read pool, then the smart-contract creates one.
Anyone can lock tokens with a read pool attached an allocation. These tokens can be used to pay read access to files stored with the allocation. To use these tokens the user must be the allocation owner, collaborator or have an auth ticket.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
blobber | no | blobber id to lock for | string | |
duration | yes | lock duration | duration | |
fee | transaction fee | 0 | int | |
tokens | yes | tokens to lock | int |
./zbox rp-lock --allocation <allocation_id> --duration 40m --tokens 1
rp-lock with a specific blobber
./zbox rp-lock --allocation <allocation_id> --duration 40m --tokens 1 --blobber f65af5d64000c7cd2883f4910eb69086f9d6e6635c744e62afcfab58b938ee25
rp-lock spread across all blobbers
Tokens are spread between the blobber pools weighted by each blobber's Terms.ReadPrice.
./zbox rp-lock --allocation <allocation_id> --duration 40m --tokens 1
Unlock tokens from read pool
Use rp-unlock
to unlock tokens from an expired read pool by pool id.
See rp-info
for the POOL_ID and the expiration.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
fee | no | transaction fee | 0 | float |
pool_id | yes | id of pool to unlock | string |
rp-unlock
./zbox rp-unlock --pool_id <pool_id>
Storage SC configurations
Show storage SC configuration.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
json | no | print result in json format | false | boolean |
sc-config
./zbox sc-config
Stake pool info
Use sp-info
to get your stake pool information and settings.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
blobber_id | id of blobber | current client | string | |
json | no | print result in json format | false | boolean |
sp-info
./zbox sp-info --blobber_id <blobber_id>
Lock tokens into stake pool
Lock creates delegate pool for current client and given blobber.
The tokens locked for the blobber stake can be unlocked any time, excluding times
when the tokens held by opened offers. The tokens collect interest.
sp-lock
returns the id of the new stake pool, this will be needed to reference
to stake pool later.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
blobber_id | id of blobber | current client | string | |
fee | no | transaction fee | 0 | float |
tokens | yes | tokens to lock | float |
sp-lock
./zbox sp-lock --blobber_id <blobber_id> --tokens 1.0
Unlock tokens from stake pool
Unlock a stake pool by pool owner. If the stake pool cannot be unlocked as
it would leave insufficient funds for opened offers, then sp-unlock
tags
the stake pool to be unlocked later. This tag prevents the stake pool affecting
blobber allocation for any new allocations.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
blobber_id | id of blobber | current client | string | |
fee | no | transaction fee | 0 | float |
pool id | yes | id of pool to unlock | string |
sp-unlock
./zbox sp-unlock --blobber_id <blobber_id> --pool_id <pool_id>
Stake pools info of user
Get information about all stake pools of current user.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
client_id | id of client | current client | string | |
json | no | print result in json format | false | boolean |
sp-user-info
./zbox sp-user-info
Pay interests
Changes in stake pool pays all pending rewards, But if there are no
changes interests will not be paid.
sp-pay-interests
command can be used to force payment of interest for
all delegates. Use sp-info
to check if interest can be paid or not.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
blobber_id | id of blobber | current client | string |
sp-pay-interests
./zbox sp-pay-interests --blobber_id <blobber_id>
Write pool info
Write pool information. Use allocation id to filter results to a singe allocation.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation id | no | allocation id | string | |
json | no | print result in json format | false | boolean |
sp-pay-interests
For all write pools.
./zbox wp-info
Filtering by allocation.
./zbox wp-info --allocation <allocation_id>
Lock tokens into write pool
wp-lock
can be used to lock tokens in a write pool associated with an allocation.
All tokens will be divided between allocation blobbers depending on their write price.
- Uses two different formats, you can either define a specific blobber to lock all tokens, or spread across all the allocations blobbers automatically.
- If the user does not have a pre-existing read pool, then the smart-contract creates one.
Anyone can lock tokens with a write pool attached an allocation. These tokens can be used to pay for the allocation updates and min lock demand as needed. Any tokens moved into the challenge pool to underwrite blobbers' min lock demands return to the allocation's owner on closing the allocation.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation id | no | allocation id | string | |
blobber | no | blobber id | string | |
duration | yes | duration for which to lock tokens | duration | |
fee | no | transaction fee | 0 | float |
tokens | yes | number of tokens to lock | float |
rp-lock with a specific blobber
./zbox rp-lock --allocation <allocation_id> --duration 40m --tokens 1 --blobber f65af5d64000c7cd2883f4910eb69086f9d6e6635c744e62afcfab58b938ee25
rp-lock spread across all blobbers
Tokens are spread between the blobber pools weighted by each blobber's Terms.ReadPrice.
./zbox rp-lock --allocation <allocation_id> --duration 40m --tokens 1
./zbox wp-lock --allocation <allocation_id> --duration 40m --tokens 1
Unlock tokens from write pool
wp-unlock
unlocks an expired write pool by its POOL_ID. See wp-info
for the pool id and the expiration.
An expired write pool, associated with an allocation, can be locked until allocation finalization even if it's expired. It possible in cases where related blobber doesn't give their min lock demands. The finalization will pay the demand and unlock the pool.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
fee | no | transaction fee | 0 | float |
pool_id | yes | id of pool to unlock | string |
rp-unlock
./zbox wp-unlock --pool_id <pool_id>
Download cost
get-download-cost
determines the cost for downloading the remote file from dStorage. The client must be an
owner, collaborator, or using an auth ticket to determine the download cost of the file.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
authticket | no | auth ticket to use if not the owner | string | |
lookuphash | no | hash of remote file, use with auth ticket | string | |
remotepath | no | file of which to get stats, use if owner | string |
get-download-cost
./zbox get-download-cost --allocation <allocation_id> --remotepath /path/file.ext
Upload cost
get-upload-cost
determines the cost for uploading a local file on dStorage.
--duration
Ignored if --end
true, in which case the cost of upload calculated until
the allocation expires.
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | string | |
duration | no | duration for which to upload file | duration | |
end | no | upload file until allocation expires | false | boolean |
localpath | yes | local of path to calculate upload | file path |
get-upload-cost
./zbox get-upload-cost --allocation <allocation_id> --localpath ./path/file.ext
Commit
Commit file changes to chain
Parameter | Required | Description | Valid values |
---|---|---|---|
allocation | yes | allocation id | string |
authticket | no | auth ticket for file to commit | string |
filemeta | no | meta for commit if applicable | string |
lookuphash | no | remote lookuphash to commit, use with authticket | string |
newvalue | no | new value for the folder operation if applicatble | string |
operation | yes | operation name for commit change | string |
remotepath | no | remote path of object to commit | string |
Sign data|
sign-data
uses the information from your wallet to sign the input data string
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
data | yes | string to sign | string |
./zbox sign-data "data to sign"
Signature : 9432ab2ee602062afaf48c4016b373a65db48a8546a81c09dead40e54966399e
Streaming
Video streaming with Zbox CLI can be implemented with players for different operating platforms(iOS, Android Mac).Zbox CLI does not have a player itself and use the the downloadFileByBlocks helper function to properly returns file-chunks with correct byte range.
How it works:
When the user starts the video player (ExoPlayer for Android or AVPlayer for iOS), A ZChainDataSource starts chunked download and requests chunks of video from the buffer(a Middleman between streaming player and Zbox).
After the arrival of the first chunk, the player starts requesting more chunks from the buffer, which requests the Zbox SDK. Zbox SDK, which is built using GO, makes use of the downloadFileByBlocks method to reliably download large files by chunking them into a sequence of parts that can be downloaded individually. Once the blocks are downloaded, they are read into input streams and added to the media source of the streaming player.
The task of downloading files and writing them to buffer using Zbox SDK happens constantly, and If players request random bits of video, they are delivered instantly by a buffer.
In a case, if the player didn't receive chunks (for example, it's still not downloaded), then the player switches to STALE state, and the video stream will pause. During the STALE state, a player tries to make multiple requests for chunks; if didn't receive a response, the video stream stops.
Usage
To understand how Zbox CLI provides downloading of files by blocks. Let's consider an allocation that has audio. mp3
file stored on dStorage. Make sure the file has a large size(more than 64 kB(64000 bytes)) to download the file by blocks. The size and other attributes of the sample audio. mp3
file can be viewed using
./zbox list --allocation $ALLOC --remotepath /myfiles
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS |LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+-----------+--------------------+---------+------------+----------------
f | audio.mp3 | /myfiles/audio.mp3 | 5992396 | 92 | 3cea39505cc30fb9f6fc5c6045284188feb14eac8ff3a19577701c4f6d973239 | NO | owner
Here we can see the audio.mp3
file of size (5993286) bytes having 92 blocks.If we want to download a certain number of blocks for the audio.mp3
file we can use the --endblock
or --startblock
flag with ./zbox download
command. Other flags for download can be viewed using ./zbox download --help
Flags:
-b, --blockspermarker int pass this option to download multiple blocks per marker (default 10)
-e, --endblock int pass this option to download till specific block number
-h, --help help for download
--localpath string Local path of file to download
--remotepath string Remote path to download
-s, --startblock int Pass this option to download from specific block number
For only downloading three blocks of audio.mp3
file, we specify --startblock
and--endblock
with integer value of 1 and 3. --blockspermarker
flag can also be specified to download multiple blocks at a time(default is 10).
Sample command for downloading till 3rd block of the audio.mp3
file would be:
./zbox download --localpath /root --remotepath /myfiles/audio.mp3 --allocation $ALLOC --startblock 1 --endblock 3
Response:
393216 / 2996198 [====================>-----------------------------------------------------------------------------------------------------------------------------------------] 13.12% 1s
Status completed callback. Type = audio/mpeg. Name = audio.mp3
As we can see, the downloaded file size(393216) is less than the original(2996198), which means zbox has downloaded some blocks of the file.
Troubleshooting
- Both
rp-info
andrp-lock
are not working.
./zbox rp-info
Response:
Failed to get read pool info: error requesting read pool info: consensus_failed: consensus failed on sharders
This can happen if read pool is not yet created for wallet. Read pool is usually created when new wallet is created by zbox
or zwallet
. However, if wallet is recovered through zwallet recoverwallet
, read pool may not have been created. Simply run zbox rp-create
to create a read pool.
Documentation ¶
There is no documentation for this package.