wolkjs v0.0.11

Wolkjs Library

Using wcloud the Wolk Command Line Interface

This presumes you have node installed.

wcloud is the wolk command line interface. It is located in the root directory of the wolkjs repository. Upon initial install, be sure to navigate to this directory and run npm install.

wcloud is a command line interface

Installing wcloud

This presumes you have node installed.

1. Navigate to a directory and clone the dev branch of wolkjs running git clone -b dev git@github.com:wolkdb/wolkjs.git
2. Move into the wolkjs directory cd wolkjs
3. run npm install

Usage

The format of the wcloud commands is as follows

wcloud <operation> <flags> <parameters>

• An is one of the supported commands like put, get, getname, etc ...
• A is a one of the supported flags. IMPORTANT: All flags start with 2 dashes (ex: --httpport=83).
  • NOTE: if you wish to set these flags via environment variables, then please be sure to use ALL CAPS (ex: export HTTPPORT=83).
• A represents an input into a given . These follow a specific order as noded below

Wolk URLS - wolk://...

A note about wolk urls. A Wolk url in the format of wolk://owner/collection/key is synonymous to making a request to https://cloud.wolk.com/owner/collection/key.

https://cloud.wolk.com is the default provider. Any miner can run a provider and make the same content available through their node. When a miner sets up a Wolk node and makes it available at say, https://wolk.newprovider.com, then the address wolk://owner/collection/key may also be requested via https://wolk.newprovider.com/owner/collection/key and retrieve the same content.

wcloud Usage

Wolk Cloudstore Usage: (*-Not implemented/tested yet)

Names/Accounts:
 GetName:      wcloud getname  name            [wolk://wolk/names/name]   (returns address associated with specified name)
 GetAccount:   wcloud account  name            [wolk://wolk/account/name] (returns account)
 SetName:      wcloud setname  name            [wolk://wolk/names/name]   (assigns name to address - returns resulting transaction hash)
 CreateAccount:wcloud createaccount name       (creates keys in key directory - default: ./keys)
 SetDefault:   wcloud setdefault name          (sets default name in ~/.wolk/default file)
 SetKeyDir:    wcloud setkeydir directory      (returns path to where local key files will be stored and retrieved)
 *DumpKeys:    wcloud dumpkeys name             (displays contents of locally stored key files for name)
 
File Buckets:
 Make Bucket:   wcloud mkdir   wolk://owner/bucket                  (creates bucket - returns transaction hash)
 List Buckets:  wcloud get     wolk://owner                         (returns the list of buckets created by specified wolk owner)
 Delete Bucket: wcloud delete  wolk://owner/bucket                  (deletes bucket - returns transaction hash)
 Upload File:   wcloud put     localfile wolk://owner/bucket/file   (uploads localfile to the wolk address specified - returns resulting transaction hash)
 Get File:      wcloud get     wolk://owner/bucket/file localfile   (returns the content at the specified wolk address AND stores it at the location specified by localfile)
 Get File:      wcloud get     wolk://owner/bucket/file             (returns the content at the specified wolk address)
 List Bucket:   wcloud get     wolk://owner/bucket/                 (returns the list of keys in the specified wolk bucket)
 *Delete File:   wcloud delete     wolk://owner/bucket/file          (deletes file - returns transaction hash)
 
NoSQL:
 Create Collection:  wcloud createcoll wolk://owner/collection         (creates collection - returns resulting transaction hash)
 Scan Collections:   wcloud get        wolk://owner/                   (returns the list of collections created by specified owner)
 Delete Collection:  wcloud delete     wolk://owner/collection         (deletes collection - returns transaction hash)
 Set Key:            wcloud set        wolk://owner/collection/key val (sets value of specified key to val - returns resulting transaction hash)
 Get Key:            wcloud get        wolk://owner/collection/key     (returns associated value)
 Scan Collection:    wcloud get        wolk://owner/collection         (returns list of keys in collection)
 Scan Owner:         wcloud get        wolk://owner                    (returns collections created by owner)
 *Delete Key:        wcloud delete      wolk://owner/collection/key     (deletes key - returns transaction hash)
 
SQL:
*Execute:      wcloud sql     owner database sql         [wolk://owner/database/]

Blockchain:
 GetLatestBlock:  wcloud blocknumber                     [wolk://wolk/block/latest]          (returns block number of last minted block)
 GetBalance:      wcloud balance address|name            [wolk://wolk/balance/address]       (returns WLK balance of specified name/address)
 GetBlock:        wcloud block blocknumber               [wolk://wolk/block/blocknumber]     (returns block associated with specified blocknumber)
 GetTransaction:  wcloud transaction txhash              [wolk://wolk/transaction/txhash]    (returns transaction associated with specified txhash)
 GetNode:         wcloud node nodenumber                 [wolk://wolk/node/nodenumber]       (returns node associated with specified nodenumber)

 Transfer:        wcloud transfer recipientaddr amount
*RegisterNode:    wcloud registernode [nodenumber] [storageip] [consensusip] [region] [value]
*UpdateNode:      wcloud updatenode registernode [nodenumber] [storageip] [consensusip] [region] [value]
*BandwidthCheck:  wcloud bandwidthcheck [checkChunkHash]

Flags: (optional)
  [all]
  --httpport=80
  --range=80-160    [cat]
  --pkey=privatekey [setkey, setname, sql, transfer, registernode, updatenode, bandwidthcheck]
  --proof=true      [getkey, get, getname, sql]
  --blocknumber=23  [balance, node, getkey, getname, sql]

Wolk node serves its users via HTTP and a command line interface.

Wolk Accounts

Users reserve names and associate their address to a specific string with this provided it has not yet been chosen:

# wcloud createaccount fawkes
{"txhash":"535c72ce4c5a4b3a78db4a1fe8d432fc3d4bd7135711ae432b2899bf5b94f8e7"}

# wcloud getname fawkes
82a978b3f5962a5b0957d9ee9eef472ee55b42f1

# wcloud getaccount fawkes
{"balance":25000,"quota":25000000000,"usage":22781,"rsaPublicKey":"eyJrdHkiOiJSU0EiLCJhbGciOiJSUzI1NiIsIm4iOiIybGNDeERDNXhaQ3ZsU1IwVE0xYXdpX3pnZkM0OWRsdlhZcjg4MUZDNnd2eWdYN0J3enZ5TGhuaTlwZDd5dTlYNVJTQVZvLTM4NXhfNlRkRDZzbkdGQ21IcG5WZjZkazdBakVUTGRTY0dROF9YTzBwVUU4Wnh4TjdJWkgzc1Z2eDdaUW5NdXV4bUtuMjhjbDIySG5qN21tUnlULUJsUjd5by10c1J5MENVbUZsRC1ydlpEQ18wQjRDOTlOVnVyLVFfMTJlSzhyb2oxTTEyeGxZdlpMMVVLM0ZOM1hybEVNd1J0a0oxbjNKVC1lVlVEQjFPQVJsa0xmcVZuY0JhNC1TckhCQXg4N1d4VnZFWGh1YjVTWmt4MUJ5VTR0M3VPVUtiWGdmQlU4VFA1dU1aSF81OXBQM0RtMDdzZVZ6V0JGNzI1WGgzTVY4eV9oRllPMlEtRWUxcnciLCJlIjoiQVFBQiIsImtleV9vcHMiOlsidmVyaWZ5Il0sImV4dCI6dHJ1ZX0="}

Wolk File Buckets and NoSQL Collections

With a name set up, a user may store files and set/get keys with familiar cloud provider interfaces that interact with a cloudstore address's has a set of buckets, which have a storage quota. Buckets are of different types: file buckets, NoSQL buckets, SQL buckets, and other bucket types.

For file buckets and NoSQL buckets, there are a set of keys mapped to fileHashes of content, and the total amount of storage used by all the storage operations. The same mechanism is used for storing files and NoSQL key-value pairs.

Generally, all operations that store content map to HTTP PUT operations, and all operations that retrieve content map to HTTP GET operations, with the wcloud interface shown here.

A special collection "buckets" is used to store metadata about the users collection.

# wcloud mkdir wolk://fawkes/planets
{"txhash":"db8d40ae0ec6fda0310120c99381d8aa782f9ceea04430f84552fc387d502a40"}

# wcloud get wolk://fawkes/
 33	planets	d083f26804b3b0740cb918cdf3a30a5bbb82d84c8dab35a1cf6ecd47808d72c7
 34	photos	8f17ac69be0a35b67fe25ed45c2dbb65c06fa19deea99bf6ba4f2a4c27730a51
 100000	videos	85e3b06bfb718ad3183fde82d0e1aeae50258354fc10e007b2a986df9c50cedc
# wcloud set wolk://fawkes/planets/pluto small
{"txhash":"8f92d2e796ee0158e0bed61c390b225584244e2831d7a12e589bd3d5e88797ac"}

# wcloud get wolk://fawkes/planets/pluto
small
# wcloud set wolk://fawkes/planets/jupiter big
{"txhash":"550b110c56ee7a28a5ffc4cb9c764f8dc08550eddeaa479a4910309bd7ece90b"}

# wcloud ls wolk://fawkes/planets
5	  pluto	42faffb02208ec37aa24a44ff1b1f8d6d4ae17eab58c5f82f33992cc8e1b545c
3	  jupiter	9c559b43ff30ffc56fc3b4808fdc33eeccf2f09141b4642fb19ca393cb83b142
10	saturn	01f1c01a94cca3c8adf7f2cf00bf5d1da2aafff41d7b6fc9277ab81e8a7cfbfb

# wcloud put wcloud/content/banana.gif wolk://fawkes/photos/banana.gif
{"txhash":"9e15486eae8566e1d53fe3c27b9991ecb48d7363a509edc74f923fc4849c16fe"}

# wcloud get wolk://fawkes/photos/
 73623	banana.gif	6f439c8124e896af214b3cceda4f249d94df3c72a350358a904a38cf8d341cea

# wcloud account fawkes
{"balance":200003,"quota":516880,"usage":8}

Proofs

All requests of wolk urls have the potential to return proofs, proving the validity of the content returned. By default wcloud does not check these proofs, however, including the --proof flag will cause this proof verification to be initiated for a particular request.

wcloud --proof --v getname fawkes
wcloud --proof wolk://fawkes/planets/jupiter

SQL operations

# wcloud createaccount simba
{"txhash":"0b15841975550ac6214e74017eee7d7644e37d89e3784e8a3966139250695707"}

# wcloud sql wolk://simba/ncis createdatabase
{"txhash":"850beeff8801f9bce17d65dc553b19305d205d667c91749a20a3eb4f5e259097"}

# wcloud sql wolk://simba/ncistest "create table personnel (person_id int primary key, name string)"
{"txhash":"3891882b0403b7092cd46dbb44c367b12ba92e2b833fc9aac1c0b4c8ada92848"}

# wcloud sql wolk://simba/ncis "insert into personnel (person_id, name) values (6, 'dinozzo')"
{"txhash":"af560ee314240c9ed6f3542843a7b702ffe8f3f5b70fe943450a373e0d4d35e6"}

# wcloud sql wolk://simba/ncis "insert into personnel (person_id, name) values (23, 'ziva')"
{"txhash":"1752e47167bea218b73c9e8b96b0640f6f2e7bbc025371cd61d9fae5e0e13a8a"}

# wcloud sql wolk://simba/ncis "insert into personnel (person_id, name) values (2, 'mcgee')"
{"txhash":"b63f503ee235e44aa64fba34afd01237ec7449d0220e06bb59bdc94ad36f9fc7"}

# wcloud sql wolk://simba/ncis "insert into personnel (person_id, name) values (101, 'gibbs')"
{"txhash":"6ab3f77fcbc6a8b808a5b17be7dfd0509fba0085ed179c4b698e5ecb870e627b"}

# wcloud sql wolk://simba/ncis "select * from personnel"
{"data":[{"name":"mcgee","person_id":2},{"name":"dinozzo","person_id":6},{"name":"ziva","person_id":23},{"name":"gibbs","person_id":101}],"matchedrowcount":4}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}

# wcloud sql wolk://simba/ncis "delete from personnel where name = 'ziva'"
{"txhash":"1feeae04389a67645dcc9ca6c913ff44d1dcb5154d5f865cde8766adde5ebd5f"}

# wcloud sql wolk://simba/ncis "select * from personnel"
{"data":[{"name":"mcgee","person_id":2},{"name":"dinozzo","person_id":6},{"name":"gibbs","person_id":101}],"matchedrowcount":3}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}

# wcloud sql wolk://simba/ncis "delete from personnel where person_id = 6"
{"txhash":"a80f4eb237c48ed564dab22c2ea127603dcee96551ad37bb2feee17c09b97f7e"}

# wcloud sql wolk://simba/ncis "select * from personnel"
{"data":[{"name":"mcgee","person_id":2},{"name":"gibbs","person_id":101}],"matchedrowcount":2}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}

# wcloud sql wolk://simba/ncis "describetable personnel"
{"data":[{"ColumnName":"person_id","ColumnType":"INTEGER","IndexType":"BPLUS","Primary":1},{"ColumnName":"name","ColumnType":"STRING","IndexType":"BPLUS","Primary":0}]}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}

# wcloud sql wolk://simba/ncis "create table awards (person_id int primary key, name string)"
{"txhash":"c7517b770692658f07331641e55492d8969f7d7b2c68de78d85d791c5657283e"}

# wcloud sql wolk://simba/ncis "listtables"
{"data":[{"table":"personnel"},{"table":"awards"}],"matchedrowcount":2}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}

# wcloud sql wolk://simba/ncis "droptable awards"
{"txhash":"ab9ec7533d342f42619bf76882637f3a9c257b084842058aca680d0b2b3981b8"}

# wcloud sql wolk://simba/ncis "listtables"
{"data":[{"table":"personnel"}],"matchedrowcount":1}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}

# wcloud sql wolk://simba/ncistest createdatabase
{"txhash":"1797301b0527e5a4452bf8194c6ee5e72b6f632033314822956cd4a539b20d76"}

# wcloud sql wolk://simba/ncis "listdatabases"
{"data":[{"database":"ncis"},{"database":"ncistest"}],"matchedrowcount":2}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}

# wcloud sql wolk://simba/ncis "dropdatabase"
{"txhash":"3f754ec09bcc02ca80c363e49af969f60169fff58649ea62d21c2c8f2d9aea00"}

# wcloud sql wolk://simba/ncis "listdatabases"
{"data":[{"database":"ncistest"}],"matchedrowcount":1}
{"txhash":"0000000000000000000000000000000000000000000000000000000000000000"}```

Blockchain Operations

wcloud also allows for the inspection of the Wolk blockchain. See below for examples of operations like querying for the things like latest minted block number and block.

Get Latest Block:

# wcloud blocknumber
507

Get Block:

# wcloud block 383
{"parentHash":"0xd519a8095d1ef23b52d72e2871795a3d85a94661c797293663aaee79020a9f57","blockNumber":383,"seed":"0x642383cea99d80118390c342e371eca0aced55b3dcbc0d57efd497e88f8ee2c5","accountRoot":"0x1b222b61e3e975c2f25aa3cdc9086665d7038617a15f18bb2a841313a142baf1","registryRoot":"0x0fca18a9a2c1b93446aa206ed8a4cd75d47975f8c2399642ea7e7b65f03e9fb0","checkRoot":"0x0000000000000000000000000000000000000000000000000000000000000000","keyRoot":"0x5bb4d8b25ed387aafa89776f7574ad235121711e844034e9609ec1d49f05d2f5","productsRoot":"0x0000000000000000000000000000000000000000000000000000000000000000","nameRoot":"0x15fa6ec968b705b2d341d81be59f39d87fd329b0ef2a3e9b45aabb5631a41206","transactions":[{"transactionType":6,"recipient":"0x82a978b3f5962a5b0957d9ee9eef472ee55b42f1","hash":"0x011b4d03dd8c01f1049143cf9c4c817e4b167f1d1b83e5c6f0f10d89ba1e7bce","collection":"cGhvdG9z","key":"YmFuYW5hLmdpZg=="}],"deltaPos":1,"deltaNeg":2,"storageBeta":30,"bandwidthBeta":40,"phaseVotes":0,"q":3,"gamma":100,"sig":""}

Get Transaction:

# wcloud tx 109a252be54ba2780950ba1dfbc6b6eea72123a6759ebd53dd0eab8bb8424070
{ txhash:
   '0x4f3d89bb1ad8b845503428c5644a6267770059ccc86e169633f6be256f21654e',
  method: 'PUT',
  path: '/rodtest/colltest/scratch.js',
  payload:
   '{"hash":"0xacc42a6c114d2ebb1f7cc21b6f2514bc7b86816dd746f81c5c9a31eb169e56b9","amount":6064}',
  sig:
   '30440220021918086e98d99befe89957a79bd7fc7b0afd059410a10d9e3078502b87b7b9022021407c5102a71957570425cff12ed9ff9b8325adee9495086545886a7ce82c3e',
  signer:
   '{"kty":"EC","crv":"P-256","x":"J1M7c35Yi7dgu88Kg74rvYNuHgxTNZL03cjxHOyKUWY","y":"Ycw5jR27e1LU3jS0W0GsbIhBcB_pLLeuaGkIXktg07Y","key_ops":["verify"],"ext":true}',
  BlockNumber: 4316,
  Status: 'Applied',
  SignerAddress: '0x129968f73c750913e2af10e2f14f3bc35ea0f05e',
  txsize: 361 }

Get Balance:

# wcloud balance 0x82A978B3f5962A5b0957d9ee9eEf472EE55B42F1
100000