(tested) 5-Minute Hello World Blockchain with Ethereum on Mac or Ubuntu

It took me three years to get around with doing the hello world version of blockchain. Here is how to do it in 5 minutes without previous knowledge.

8 min readNov 26, 2018

TL;DR

It might be very easy to setup a blockchain, make some transactions and create your own smart-contact. But it’s incredibly difficult to really get it right in the way that actually makes the world a better place. In this article you learn how to setup a blockchain easily, and what happens when stuff breaks and the world becomes a worse place.

when things go wrong with blockchain
blockchain taxonomy / hierarchy
setting up a local blockchain
creating a genesis file
start mining on the blockchain
creating more accounts on the node
transferring assets between accounts
creating a second node
transferring assets between nodes

Death by a Thousand Script Kiddies: A Cautionary Tale

This article is not a fast track to a public blockchain or production ready smart contracts. In fact this particle might very well take you further from such lofty ideas. The article just provides the simplest, the most transparent way of creating a local blockchain and effectively works towards feeling less like…

There are two words we need to carefully consider before moving on; contract and ledger. Words like these are kind of a big deal. Especially when you mix them with words likes trustless and consensus. When you fail to appreciate this, *stuff* happens. Still, a lot of blockchain projects seem to be built using the same approach as one would use for building an android app or a website. One reason is demographics.

As an example of monkeys producing a Hamlet: consider the curious case of devops199. He was able to easily (or she) freeze US$300 million worth of assets on multi-sig wallets provided by Parity Technologies. It seems relevant to consider that Parity is a company founded by Ethereum’s original CTO Gavin Wood. Also bare in mind that this was a second hack in less than 6 months effecting users of Parity’s wallet.

The Github issue associated with the (second) Parity multi-sig wallet hack

Is it still more concerning how Gavin Wood seemed to trust Parity’s multi-sig wallet; his $90 million Polkadot ICO stash was frozen with the other $210 million. In other words, we have all the reasons to believe that Gavin Wood thought that his company’s code was solid (no pun intended). Next time when you hear the word “trustless”, this is a good story to keep in mind.

And yea…

Long story short, Parity’s play for recovering the assets involve changing the Ethereum code in a way that assumes no mistake was made on Parity’s part. Begs the question…is that really different from the government bailing out a private bank? That escalated fast.

The key learning here is to play safe. This article is not helping you to get started with blockchain, it just shows how to be less confused about it.

Taxonomy / Hierarchy

In one way blockchain is a decentralized technology, and at the same time it is based on a conventional taxonomy / design paradigm. Basically there is a bunch of stuff that is made of bunch of other stuff, and that stuff is made of some other stuff.

In this vein, it appears that the structure of a blockchain is:

Blockchain is made of nodes
Nodes are made of accounts
Accounts are made of addresses

It is the way these things interact with each other that give blockchains the sense of decentralization they come with.

Setting Up a Local Blockchain

Without further ado, let’s do this. First, some packages need to be installed. Namely the Ethereum blockchain. We’ll use Solidity in the Part 2, so you don’t have to install that now if you don’t want to. Note that the installation might take a while, so be prepared to wait.

ON MAC

brew update
brew upgrade
brew tap ethereum/ethereum
brew install ethereum

ON UBUNTU

sudo apt-get install software-properties-common
sudo add-apt-repository -y ppa:ethereum/ethereum
sudo apt-get update
sudo apt-get install ethereum

From here onwards, I’ve done everything on Mac but it should work on Ubuntu with the exact same commands.

First we have to use a Genesis File to initialize the blockchain. Consider it as the config file for your blockchain. It’s how you set parameters that affect the way your blockchain works. Before doing anything else, we need to decide those parameters and create a simple (fear not) json file with the configuration. Apparently there are just four parameters that are required:

config (the actual config)
difficulty (mining difficulty; the smaller the number the easier/faster)
gasLimit (the max amount of gas needed per block)
alloc (pre-allocation of Ether to given addresses)

If you want to learn about gas and difficulty, it’s easy to find many articles that explain those concepts.

First Example Genesis File

{
  "config": {
    "chainId": 1907,
    "homesteadBlock": 0,
    "eip155Block": 0,
    "eip158Block": 0
  },
  "difficulty": "10",
  "gasLimit": "2100000",
  "alloc": {}
}

Second Example Genesis File

{"config": {"chainId": 15,"homesteadBlock": 0,"eip155Block": 0,"eip158Block": 0},"difficulty": "20","gasLimit": "2100000","alloc": {"7df9a875a174b3bc565e6424a0050ebc1b2d1d82": 
    { "balance": "300000" },"f41c74c9ae680c1aa78f42e5647a62f353b7bdde": 
    { "balance": "400000" }}}

The difference in the second genesis file example is that difficulty is set to slightly higher, and some Ether is allocated on two accounts from the get-go. Next we can use the genesis file to create a node, and an account on that the node.

}# create a node on the blockchain
geth --datadir node1 init genesis.json# create a new account on the node1
geth --datadir node1 account new

For the account creation part, it’s going to prompt you for the passphrase. Once that’s done, we can login to the console:

# login to the console
geth --datadir node1 --networkid 98765 console

That’s it, you’re running a local blockchain on your machine with a single node, and a single account. For now there is really nothing on the blockchain i.e. no blocks have been mined yet, which you can verify easily:

eth.blockNumber

Which will return 0 to confirm that no mining have taken place. So let’s start a miner and make some (local) eth.

Start Mining on the Blockchain

In order to generate some Ether (assuming you did not do any pre-allocation in the genesis file), we have to mine some blocks. You can do that by:

miner.start()

This will start a miner with a single thread. After a little while mining will commence, and you will see something like:

Once this is going on, you can stop mining at any point with:

miner.stop()

Note that the log might still be updating while you type the command. That’s ok, just keep typing and hit enter. Now the block number should have changed. Go ahead and check it out.

eth.blockNumber

Now it’s a good time to check the balance for the account. There are several ways to do this:

# without knowing the account address
eth.getBalance(eth.accounts[0])# with account address 
eth.getBalance("0x63111397ab6116c68e68fc346697b466ca30f010")

As you might guess from the above example, you can get the account address using indexing:

eth.accounts[0]

Creating More Accounts on the Node

A node can have more than one account. We can do this simply by repeating the same code as we used before to create the first account on the node. First get out of the geth console and back to the command line, and then:

geth --datadir node1 account new

Now you can start the console again (as per you did previously) try:

# see the address of the account 
eth.accounts[1]# get the balance of the account 
eth.getBalance(eth.accounts[1])

Obviously the balance is 0 as the new account have not been involved in any mining, or transactions. So let’s move to making transactions.

How to make transactions between two accounts

As a simple example, let’s make a transaction from the first account we created, to the second. But before that’s possible, the sending account needs to be unlocked.

web3.personal.unlockAccount(web3.personal.listAccounts[0], "test0123", 15000)

This is going to open the Account 0 for 15000 seconds. You probably don’t want to habituate yourself in using ‘test0123’ as a password by the way. Just saying.

Then next we can perform the actual transaction:

eth.sendTransaction({from: eth.accounts[0], to: eth.accounts[1], value: web3.toWei(3, “ether”)})

Here we are making a transaction from the account 0 to account 1, worth 3 ether. At this point even though it seems that we had already “made” the transaction, it needs to be processed through the activity of mining. So let’s go ahead and to that next:

miner.start()

It might take a moment, but once you see some blocks have been mined, you can stop with:

miner.stop()

Now go ahead and check out the balance for the account 1, and it should have been updated with the 3 ether that was transacted.

eth.getBalance(eth.accounts[1])

Note that the number you see is something like 3000000000000000000 which is not ether but Wei which is a very small fraction of ether.

Creating more nodes on the blockchain

Next, let’s add more nodes to help a more illustrative example of a blockchain. First you have to create a new node (better in a separate terminal window) just as we did before with node1, but now for node2. Note that we will end up with two separate folders.

# create an additional node on the blockchain
geth --datadir node2 init genesis.json# create a new account on the node2
geth --datadir node2 account new

Next, go into a separate console session:

geth --datadir node2 --networkid 98765 --port 30306 --nodiscover console

Note that we have to use a different port as the default port is already in use by node1. Once inside the console, you need to get the enode address for node2.

admin.nodeInfo

Once you have the enode address, it’s time to go back to the original console window with node1 and add the new Peer into the network:

admin.addPeer("enode://5eac4deecf5225ad75c9e4fe885d114e2a0e440f6192e45a5a1b7833d54ed89fd3684ea15572d169b571789267a646ae8f8dcd5b8aec8090f21b1b85c263c89f@[::]:30306?discport=0")

If you get a valid output, you can now start mining on one of the nodes and see the other node update automatically. Now you could for example transact tokens from an account on one node to an account in another node:

eth.sendTransaction({from: “0x8066ee739acb45cba05f4417409d35445490fb4b”, to: “0xc90f8ff7868d0b7a3938ef637aeb64ddaa429d79”, value: web3.toWei(3, “ether”)})

Alternatives to the Geth Ethereum client

As you probably noted, I’ve used the OG client for Ethereum; Geth. There are alternatives that might make working with Ethereum blockchains more streamlined, for example from Parity. Remember the old Chinese proverb though, “when on the back of a tiger, thread carefully”.

Creating and Transacting on a Smart Contract

To keep this article reasonably straightforward, I’ve split it in three parts. In the second part we’ll cover how to do a Hello World Smart Contract on Ethereum using the blockchain we’ve just setup.

ps. Huge thanks to Alan Buxton who took the time to go through these motions and document it. I’ve mostly just cleaned his original report up and presented it in a slightly more accessible format.