Deprecation Warning

Please note this post refers to a deprecated version of the Eris stack. It is retained for historical purposes.

Note – 2gather is no longer supported. This blog post is kept ONLY for historical reasons.

How 2gather works

Introduction

The 2gather video sharing service is the first real distributed application built on Eris. It uses a number of different components:

1. EPM A command-line blockchain configuration and smart contract deployment tool.
2. Thelonious A blockchain client.
3. IPFS A p2p file-sharing client.
4. Atë A scripting component.
5. Decerver Contains Ate, some dapp-loading and verification code, and serves the dapp locally in the form of a RESTful web-API.
6. A web-browser Communicates with the decerver over http, and does all the presentation (like in any old webapp).
7. Docker Puts the various different components into containers that can be run on any platform.
8. Tutum Is used to host a peer-server for the Eris-run blockchain, and to deploy and coordinate a world-wide network of “base nodes”. More info can be found here.

This document focuses on 2gather, but most of it applies to any dapp.

Starting 2gather

Despite all of these different components, the process for starting up and running 2gather is fairly simple. Right now, users must makes sure that docker and docker-compose are installed. If it’s a Windows or Mac machine, then they need to use a tool such as boot2docker. Once that is taken care of, it’s a simple matter of pulling the 2gather repository, cd’ing in to the root and typing (sudo) docker-compose up. This will automatically pull in all the dependency containers from dockerhub (erisdb, decerver and ipfs), and generate the 2gather container and link it up with the dependencies, and start running the dapp.

The generation of the 2gather container includes the following steps:

1. Setting up the volumes and ports and all of that, so that it can run.
2. Fetching the (public) 2gather chain from the peer-server, which means initializing a local database and download the current blocks into it, as well as setting up some of the identifiers that the Thelonious blockchain client needs in order to run it.
3. Making sure the package.json of the containerized dapp is updated with the 2gather chain Id and root contracts.
4. Starting up the decerver, which will in turn start Thelonious and IPFS, make sure Thelonious is given the correct chain and root contract, and that IPFS gets a proper peer id and such. When that’s been taken care of it will load in the actual dapp-logic (which is written in javascript) and start the server.

When all of this is done, the dapp can be interacted with by opening up a web-browser and loading the url localhost:3000/2gather/. The first time this is done it will have to download all the base containers which usually takes a few minutes. When they are all in place, it normally takes something between 20-30 seconds. A lot of these containers are also shared between a lot of different dapps (and also other docker-based applications), so having them will speed up the loading of other docker-based apps as well.

Running 2gather

When 2gather is running it mostly just sits around waiting for things to happen. There are three main entry-ways for events. The first and second is the IPFS and Thelonious peer networks, and the third is browser activity (such as the user clicking on the ‘add new video’ link.

It is important to remember that the deCerver only serves locally (by default). It is not how you communicate with other peers. The way you reach other people that are on the same blockchain is over the Thelonious peer network. The way you get actual video files/data, is over the IPFS peer network. It works similar to how a bittorrent client works. It may have a Java Swing/FX or Qt GUI, for example, or in some cases you could have it serve a webpage, and that is how you access the client and send various different commands. The actual networking happens through the peer-to-peer network that the client runs. The big difference here is you have two peer networks running with 2gather - one for the blockchain and one for files. The way these systems are linked and coordinated, though, is through the decerver, and that’s what we’re going to look at next.

Example - uploading a video

Let’s say i click on the link to upload a video. What happens is this:

1. The browser will take the file url and load the video data into memory.
2. It then sends a POST request to the endpoint {BASE_URL}/users/:whatever/videos/. The request body will contain the video data and the display name.
3. The decerver receives this request and the router will pass it on to the addVideo function (or return an error if there are any issues).
4. The addVideo function will write the video data to IPFS, and get a hash in return, which is the file identifier and is used to fetch it.
5. The hash is written to a smart contract along with the file display name and some meta data. This is done by sending a transaction to the Thelonious client. By the way - this write procedure is essentially the same as in hello-world, although more work is needed before the actual write in order to handle read/write permissions, making sure each user has their own contract, and other things.
6. The transaction is queued right away, and a transaction hash is returned by the thelonious client. This hash is sent back in the response to the client, which will then continue to poll {BASE_URL}/txs/:hash until it confirms that the tx has been processed.

Step 1 is done in the webpage that comes with 2gather by default, and the code can be found in 2gather/script (index.html) is in the root). The webpage uses angular + bootstrap. The webAPI (+ tests) can be found in 2gather/spec/.

Steps 2-5 are not done automatically by the deCerver; they are part of the back-end javascript that is loaded into and executed by the deCervers javascript interpreter, and can be found in 2gather/models/. The file 2gather.js Has the startup logic and basic routing in it. The file 2gatherAPI.js contains the 2gather api (the actual logic for 2gather), and finally decerver_api.js has some generic functions for doing transactions and reading/writing to IPFS.

An Eris dapp - now and in the future

When working with 2gather we’ve noticed a few issues that needs to be addresed so that building dapps on Eris becomes easier and more intuitive. Some of these issues are:

1. The use of alpha/pre-alpha dependencies made it difficult to work at times (though we didn’t have much of a choice).
2. Manually building Go-programs is not easy. People have been struggling with this.
3. Using our tools is not easy. People have been struggling with deCerver, Thelonious and EPM. There are many components and a lot to keep track of.
4. Using LLL for contract writing is not easy.
5. Continuing to rely on some of our sub-systems/dependencies will make it hard for us to work efficiently.

Some of the solutions we’re working towards currently are these:

1. The dependency problem has been solved by itself to some degree, as IPFS and other libraries are now more mature.
2. Docker is a great deployment tool, that will replace the manual build process for DApps.
3. We’re switching over to a Node.js-based platform, so that working with dapps becomes more natural to people, mostly for those that are good (or even great) application makers, but haven’t really gotten into decentralized stuff yet. The Node.js platform will also include browser-based blockchain creation and management.
4. We’re switching over to the new Solidity contract writing language that is currently being developed.
5. We will be moving portions of the Thelonious client over to Tendermint, and some other things.