Friday, May 15, 2015

Building an ethereum ÐApp, pt. I

What is ethereum and ÐApps? Check here  or search
This is part I of a series. Part II
This article is from May 2015, check the update in Part IV

This is a collection of notes as I was going through writing a simple proof of concept ÐApp, hopefully it would prove useful to others and reduce their bleeding when working with such cutting-edge technology. I hope to address also some practical concerns which are beyond the scope of other basic tutorials.

I first met the ethereum project on a meetup in Hong Kong in summer 2014 where Vitalik Buterin presented the project himself. Since then, I've been watching it and growing more interested and after realising its potential (through Vitalik's posts on I got so excited that I went ahead and started writing my own ÐApp, like a true hacker nerd.

ÐApp components, structure

The most important part is, of course, the ethereum client (currently go-ethereum or geth). It is also called a node because it connects with other nodes to form the network (nodes usually also run mining) and you may also think of it as a wallet (in the bitcoin sense) because it keeps your private key and allows you to send transactions. As such, users of your ÐApp will either need to run their own ethereum client or use a web based service (a parallel to but that means increased centralisation and having to trust that service.

Another part of any app is the GUI. That's something you'll be building yourself. You can go ahead and use any of the old boring GUI frameworks such as Qt, HTML5, Android as long as you know how to connect to the wallet of your user. The connection happens over HTTP JSON-RPC (documentation here) which means that even an JS/HTML5 GUI served over the web can still connect to a wallet on the localhost.

Since storage and processing on ethereum blockchain is not so cheap, you may also want to run your centralised server in the old fashioned way, such as Node.js on Amazon EC2 or a Haskell server on your Commodore 64 in your grandma's basement (that would be slower than the ethereum blockchain actually, but equal in coolness factor). This server would handle data that doesn't need to be protected by the blockchain. Remember, the point of blockchain is to have a global consensus on sensitive data (such as people's account balances, domain name registrations) and making sure they are not modified behind anyone's back. Other, more trivial or sizeable data for your app, however, can be stored outside the blockchain, for example uploaded files / pictures / videos. Your server may need to run the ethereum client too, to have access to the latest blockchain state.

Installing and running geth

There's not much to say here, just follow the homepage I recommend just downloading the binaries, they are built automatically for Windows, OSX, Ubuntu. Currently, go ahead with the develop branch. Don't bother with the Mist user interface, geth is all you need (also love). I also recommend going through the Frontier Guide that is being collected at and trying out the examples to understand more.

If, upon starting geth, you can't connect to any peers, try to start with 

geth --vmodule=udp=6,server=6,downloader=6 console

to get extended logging for the network. Make sure your computer clock is correct. Note that the message about no UPnP device found means that it couldn't setup port forwarding on your router using UPnP automatically. No big deal.

Getting a Meteor app skeleton

For this project GUI+centralised server, I chose the Meteor webapp client and server framework because it's new, hip, cool and everybody else seems to be using it too. Hopefully it'll make me look cool too. If you've never heard about it, let me summarize it as a batteries-included, everything-prepared framework that bundles Node.js, MongoDB, reactive (autoupdating) templating engine and other tools to make building and deploying webapps really easy. Both server and client code are written in Javascript. You may want to go through the tutorial to get some idea on how things are working there. 

I started by installing meteor from the homepage at and then cloning this useful repo as the basic template. Meteor is by default running on port 3000. Then, start geth with JSON RPC enabled (default port is 8545) and allow CORS so that your Meteor app can access it from the browser:

geth --rpc --rpccorsdomain "http://localhost:3000" console 2> geth_stderr.txt

Note: do NOT use --rpcaddr "" or you'll lose money. Also, enable firewall to prevent access to your node from the outside.

To see log messages, watch the file geth_stderr.txt, ideally using tail -f geth_stderr.txt. You'll still need to interact with the client in the JS console it provides, don't forget to check out the documentation.

I can already feel your head exploding from the overflow of information in this and the linked articles. Let's wrap it now, have a good sleep and next continue with some actual code, perhaps even with some troubleshooting tips (for free!). I'm planning to put my little ÐApp on github as well, sometime very soon. 


  1. What does 'Note: do NOT use --rpcaddr "" or you'll lose money' mean?

  2. Having as your --rpcaddr will allow other computers on the network to connect to your wallet and issue transactions. Keep it on the default value which only allows programs from your local machine such as websites. Then you need to carefully select the websites that you allow, thats why we use --rpccorsdomain "http://localhost:3000"