wolkjs
v0.0.11
Published
WOLK JavaScript API
Downloads
2
Readme
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.
- Navigate to a directory and clone the dev branch of wolkjs running
git clone -b dev [email protected]:wolkdb/wolkjs.git - Move into the wolkjs directory
cd wolkjs - 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).
- NOTE: if you wish to set these flags via environment variables, then please be sure to use ALL CAPS (ex:
- 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/jupiterSQL 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
507Get 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