/* Remove a KVP */

function eliminate(string _key) onlyOwner public payable

{

remove(_key);

}

You may notice that all four functions have the payable keyword in their declaration. This is to indicate that these four functions require a fee in ETH in order for Oracalize servers carry out the data request to the Bluzelle swarm.

For example, to create a new key-value pair, simply execute the add(key, value) in your dApp, and send (for example) 0.002 eth in the transaction. Provided this amount is at least as much as Oracalize’s fee requirements for such a transaction, the request will be made to the swarm. If the amount of ETH transferred is actually more than Oracalize’s fee requirements, then a portion of the amount sent is accepted and the rest is returned back to your dApp contract. The user is free to simply execute the retrieveETH function to retrieve unused ETH, as per the example.

Once a CRUD operation is executed, and data is sent to or requested from the swarm, one simply has to wait for the __callback function to be executed by Oracalize. In the dApp, one can modify the __callback function in whatever way they wish, for the data to be handled appropriately.

The developer can decide whether to change the state of business logic within the smart contract, or simply emit an event. Please see SampleDapp.sol, SampleDappPublic.sol and Bluzelle.sol for a real such example:

https://github.com/bluzelle/bluzelle-sol/tree/master/contracts

Interested developers are free to try out an already deployed dApp available for the general public. Simply go to:

https://www.myetherwallet.com/#contracts

and select the Ropsten network. Then use the contract address:

0xeA6Fa8C8e59FFc5B0DffF1613B7D09e7617b9FD4

and the following abi:

[{“constant”:true,”inputs”:[],”name”:”last_value_read”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”_uuid”,”type”:”string”}],”name”:”changeUUID”,”outputs”:[],”payable”:false,”stateMutability”:”nonpayable”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”myid”,”type”:”bytes32"},{“name”:”result”,”type”:”string”}],”name”:”__callback”,”outputs”:[],”payable”:false,”stateMutability”:”nonpayable”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”newOwner”,”type”:”address”}],”name”:”changeOwnership”,”outputs”:[],”payable”:false,”stateMutability”:”nonpayable”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”myid”,”type”:”bytes32"},{“name”:”result”,”type”:”string”},{“name”:”proof”,”type”:”bytes”}],”name”:”__callback”,”outputs”:[],”payable”:false,”stateMutability”:”nonpayable”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”_key”,”type”:”string”}],”name”:”eliminate”,”outputs”:[],”payable”:true,”stateMutability”:”payable”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”current_uuid”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”last_result_received”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”apiCreate”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”last_key_used”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”owner”,”outputs”:[{“name”:””,”type”:”address”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”_key”,”type”:”string”}],”name”:”getValue”,”outputs”:[],”payable”:true,”stateMutability”:”payable”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”keyExists”,”outputs”:[{“name”:””,”type”:”bool”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”_url”,”type”:”string”}],”name”:”changeURL”,”outputs”:[],”payable”:false,”stateMutability”:”nonpayable”,”type”:”function”},{“constant”:false,”inputs”:[],”name”:”retrieveETH”,”outputs”:[],”payable”:true,”stateMutability”:”payable”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”apiRemove”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”_key”,”type”:”string”},{“name”:”_value”,”type”:”string”}],”name”:”set”,”outputs”:[],”payable”:true,”stateMutability”:”payable”,”type”:”function”},{“constant”:false,”inputs”:[{“name”:”_key”,”type”:”string”},{“name”:”_value”,”type”:”string”}],”name”:”add”,”outputs”:[],”payable”:true,”stateMutability”:”payable”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”apiRead”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“constant”:true,”inputs”:[],”name”:”apiUpdate”,”outputs”:[{“name”:””,”type”:”string”}],”payable”:false,”stateMutability”:”view”,”type”:”function”},{“inputs”:[{“name”:”_uuid”,”type”:”string”}],”payable”:false,”stateMutability”:”nonpayable”,”type”:”constructor”},{“anonymous”:false,”inputs”:[{“indexed”:true,”name”:”prevOwner”,”type”:”address”},{“indexed”:true,”name”:”newOwner”,”type”:”address”}],”name”:”OwnershipChanged”,”type”:”event”},{“anonymous”:false,”inputs”:[{“indexed”:false,”name”:”_action”,”type”:”string”},{“indexed”:false,”name”:”_key”,”type”:”string”},{“indexed”:false,”name”:”_response”,”type”:”bool”},{“indexed”:false,”name”:”_timestamp”,”type”:”uint256"}],”name”:”swarm_response”,”type”:”event”},{“anonymous”:false,”inputs”:[{“indexed”:false,”name”:”_key”,”type”:”string”},{“indexed”:false,”name”:”_value”,”type”:”string”},{“indexed”:false,”name”:”_timestamp”,”type”:”uint256"}],”name”:”swarm_read”,”type”:”event”}]

Javascript Development

Javascript development can take two general forms — node.js applications running server side and web applications running in a browser, both of which can directly talk to the Bluzelle swarm via Bluzelle’s JS libraries. The idea here is to download and refer to the JS libraries and then make the correct requests to connect to the swarm, and then await the asynchronous response.

Using Bluzelle in a JavaScript application is easy.

Run:

npm install bluzelle

in your project root, then include bluzelle with:

const bluzelle = require(‘bluzelle’);

To connect to a server, give the host and port of a Bluzelle node, and supply a unique uuid for your database.

The Bluzelle API functions implement common database functions for key-value pairs, such as creating and reading. The complete API documentation is available at:

https://bluzelle.github.io/api/

It is vital to develop using an asynchronous pattern that properly expects and processes the response to the requests before subsequent dependent requests are made. This is generally achieved through the use of JavaScript promises (MDN, Google Developers). Ensure that dependent requests are handled with .then() syntax, and that asynchronous errors are caught and handled.

Below is a sample application using the Bluzelle JavaScript API.

const bluzelle = require(‘bluzelle’); bluzelle.connect(‘ws://testnet.bluzelle.com:51010’, ‘45498479–2447–47a6–8c36-efa5d251a283’); bluzelle.create(‘myKey’, ‘myValue’).then(() =>

{

bluzelle.read(‘myKey’).then(value =>

{

console.log(value); // ‘myValue’

}).catch(e => console.log(e.message));

}).catch(e => console.log(e.message));

Bluzelle Wire Protocol Changes

For the Lovelace release we have changed our wireprotocol from a JSON-based protocol to use Google’s Protocol Buffers (protobuf).

Protocol buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data — think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages.

Since the Bluzelle swarmDB wire protocol is based on protobuf, you will need to install the protobuf compiler to use the functionality below.

Ubuntu

$ apt-get install protobuf-compile

MacOS

$ brew install protobuf

(pay attention to the instructions and output… in case you have an older version of protoc or protobuf, you might need to run “brew link — overwrite protobuf”)

Language and Platform-agnostic Development

Possibly the most critical area of development for the Bluzelle ecosystem is the ability to build drivers and integrations directly with the Bluzelle swarm, where the result is potential access to the swarm from a new programming language or platform, or where the developer needs very low-level direct access to the swarm. This is where Bluzelle’s low-level interfaces shine, with exposure to a WebSockets API.

One may establish a manual WebSocket connection using the same host and port as in the other examples. The protocol is to send a string-encoded request message, and receive a serial response. After the response is received, the WebSocket connection closes. A new connection must be established for subsequent requests.

The full WebSocket API documentation can be found at the following link:

https://bluzelle.github.io/api/#websocket-api

Ensure you have installed protofbuf, as per the section above titled “Bluzelle Wire Protocol Changes”.

Python using protobufs

First you need to clone the swarmdb repo:

In the pyBluzelle directory run (this command is not verbose and success might mean no actual output):

$ protoc — python_out=./ — proto_path=swarmdb/proto bluzelle.proto database.proto audit.proto

Setup a Python virtualenv to run the package in:

$ sudo pip install virualenv $ virtualenv crud-app $ source crud-app/bin/activate $ sudo pip install protobuf websocket-client

Python example of reading a key from the swarm:

#!/usr/bin/env python2.7 # Example of reading a keys value from the swarm https://bluzelle.github.io/api/#websocket-api import websocket import json import base64 import bluzelle_pb2 import database_pb2 # Read a key msg = bluzelle_pb2.bzn_msg() msg.db.header.db_uuid = “b3fb1002–3702–4937–8a08-bfb53b0332c8” msg.db.read.key = “release” request = {} request[“bzn-api”] = “database”; request[“msg”] = base64.b64encode(msg.SerializeToString()) ws = websocket.create_connection(“ws://testnet.bluzelle.com:51010”) ws.send(json.dumps(request)) response = database_pb2.database_response() response.ParseFromString(ws.recv()) print(“Response:

{}”.format(response)) ws.close() $ python hello.py Output: Response:

header {

db_uuid: “b3fb1002–3702–4937–8a08-bfb53b0332c8”

} resp {

value: “lovelace”

}

HTTP API

As quick helper functions, you can also refer to an early version of the HTTP API that enables direct access to the swarm to make CRUD requests. Note that this API is still being refined and is under development, for Bernoulli.

# Create

$ curl — data “lovelace” -L http://testnet.bluzelle.com:8080/create/b3fb1002-3702-4937-8a08-bfb53b0332c8/release ack

# Read

# Update

$ curl — data “ontime!” -L http://testnet.bluzelle.com:8080/update/b3fb1002-3702-4937-8a08-bfb53b0332c8/release ack

# Delete

$ curl — data “-” -L http://testnet.bluzelle.com:8080/delete/b3fb1002-3702-4937-8a08-bfb53b0332c8/release ack

Python Development

Python development is straightforward and requires the user to include the Bluzelle Python library file. The idea here is to download and refer to the Python library and then make the correct requests to connect to the swarm, and await the response. Setup a Python virtualenv to run the package in:

$ sudo pip install virualenv $ virtualenv crud-app $ source crud-app/bin/activate

Your prompt will indicate that you are in the virtualenv:

(crud-app)$

In order to install the pyBluzelle package in your local environment you will need to checkout from source:

Since the Bluzelle swarmDB wire protocol is based on protobuf you will need to install the protobuf compiler. Ensure you have installed protofbuf, as per the section above titled “Bluzelle Wire Protocol Changes”.

Once you have your protobuf compiler installed you can compile our protobuf IDL. In the pyBluzelle directory run (this command is not verbose and success might mean no actual output):

$ protoc — python_out=./pyBluzelle/proto — proto_path=proto/proto bluzelle.proto database.proto audit.proto

With the additional compiled protobuf python files you can now install the python module. Run:

$ pip install -r requirements.txt $ pip install .

This enables the ability to interact with the database programmatically as part of a Python server or client application or with a crud command line tool. Let’s walk through an example connection application in the python console:

$ python >>> import pyBluzelle >>> b = pyBluzelle.create_connection(“testnet.bluzelle.com”, 51010, “45498479–2447–47a6–8c36-efa5d251a283”) >>> b.create(“myKey”,”myValue”) >>> b.read(“myKey”) ‘myValue’

Launching your own private testnet swarm

In many cases, the most optimal way for you to develop and work with the Bluzelle swarm is to run your own swarm, isolated, and within the confines of your own machines or network(s). Running your own testnet is quite simple and still affords you access to all the connectors, libraries, and other tools that are available on the public testnet. In order to facilitate the deployment of private test swarms, Bluzelle has implemented quick deploy docker-compose script that will automatically initialize and configure a three node swarm. Start by cloning the docker-swarm-deploy repository:

$ git clone https://github.com/bluzelle/docker-swarm-deploy $ cd docker-swarm-deploy

Now you need to setup your local environment to run the swarm. Locate the local interface IP address using the following command:

$ ifconfig en1

en1: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500

inet6 fe80::1837:c97f:df86:c36f%en1 prefixlen 64 secured scopeid 0xa

→>inet 192.168.0.34 netmask 0xffffff00 broadcast 192.168.0.255

nd6 options=201<PERFORMNUD,DAD>

media: autoselect

status: active

In the above case, the IP address of the local interface is 192.168.0.34. If you do not see inet <ipaddress>, run ifconfig and comb through manually to find your local IP address. Your output might vary depending on operating system. The example here is based on MacOS.

Modify the .env file at the root of the docker-swarm-deploy repository to include the local interface IP.

…

LOCAL_IP=192.168.0.34

…

Next you need to create an Etherscan account. Go to https://etherscan.io/register and create an account. Create an Etherscan API KEY by clicking Developers -> API-KEYs and once again add that to your .env file at the root of docker-swarm-deploy.

…

ETHEREUM_IO_API_TOKEN=***********************

… Finally, modify the .env file to include an Ethereum mainnet address that contains tokens or use the sample address provided below. …

ETHEREUM_ADDRESS=0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a

…

That’s it. You’re done. All you need to do is bring up the swarm with:

$ docker-compose up

You can now interact with the database on ports 51010–51012.

Bernoulli

Looking past Lovelace, we are excited to move onto development of Bernoulli, the next stage in the Bluzelle DB roadmap. Named in honour of Daniel Bernoulli, I chose this name to recognize the immense value of Bernoulli’s principle. It is the fundamental principle behind the design of the airplane wing, which makes aviation possible.

Daniel Bernoulli

Bernoulli will come with several powerful features, including but not limited to the following:

Decentralization of the discovery of Bluzelle swarm nodes, via the use of an Ethereum smart contract. This smart contract acts like an entry point for DB consumers to connect to the Bluzelle DB without having prior or cached knowledge of the whereabouts of Bluzelle nodes. It is an important step in truly decentralizing the Bluzelle database, from a bootstrapping standpoint.

A RESTful HTTP API to make direct requests to the swarm via curl, etc.

A GUI CRUD client will be released that can be used by the public. It will have interfaces both on the web browser as well as native (MacOS, Windows, Linux, etc) versions to run on your desktop, and will allow you to directly work with your Bluzelle DB data whether that data is a simple scalar or a full-on JSON document. In Lovelace, we will be showing early concepts of this CRUD client, restricted for now to private use.

The Bluzelle emulator will be released to the public, ready for developers to emulate the swarm and build software directly against the emulator, without the need to launch a testnet swarm. This is a powerful feature that streamlines the development process and makes it even simpler for developers to work with the Bluzelle DB.

Open Source Community & CLA

Another major development to coincide with the release of Lovelace is the Bluzelle CLA, also known as the contributor license agreement. With the CLA, we can officially start to accept contributions from members of the open source community who agree to the terms of the CLA. These people become valued members of the Bluzelle ecosystem and are able to make and approve pull requests in their respective projects. For example, the PHP and Ruby implementations being released with Bluzelle are being developed by members of the open source community under the CLA. The core daemon is licensed under AGPLv3 while the libraries use highly permissive licenses (ie: MIT) that encourage application development.

As always, we welcome contributions in the form of applications, drivers, integrations, bug fixes, comments, etc. If you feel the need to make an improvement/fix to existing code anywhere in the ecosystem, please submit a pull request. In some cases, we will issue bounties for certain requests that get fulfilled by the public. These bounty requests might take the form of bugs that need fixing, features, or even entire applications or drivers or integrations.

Our developer channel has moved to Gitter. Stay connected with us!