How to set up a private Ethereum testnet blockchain using Geth and Homebrew

About me

Hi, my name is Lander. I’m a Digital Consultant and product builder from Belgium. When I’m not dabbling in Solidity, I’m working on Defihut, a platform for Decentralised Finance news, tutorials and interviews.

About this tutorial

This tutorial is an interpretation of different resources that helped me get up & running setting up my first private Ethereum testnet blockchain using Geth and Homebrew. It serves as a future reference for myself and as a help for other crypto enthusiasts. I tried to list most of my resources at the bottom of this article. Please let me know if you feel anything’s missing.

Private Ethereum testnet blockchain

Ethereum software enables a user to set up a “private” or “testnet” Ethereum chain that is separate from the main Ethereum chain. This is useful for testing distributed apps built on Ethereum without having to expose your apps to the real Ethereum network using real Ether. You either pre-generate or mine your own Ether on your private Ethereum chain, so it is a much more cost effective way of trying out Ethereum. Have I said Ethereum enough?

What do you need for this tutorial?

A few assumptions

• - You are using MacOS
• - You are a crypto and/or software development enthusiast who’s wanting to make his/her first steps into writing smart contracts.
• - You know what Ethereum is and understand it’s basic usage.
• - You have a basic understanding of MacOS Terminal usage.

What will you achieve?

After successfully completing this tutorial, you’ll have a fully functional private Ethereum testnet blockchain running on your local computer.

This private testnet will allow you to develop and test your current Dapps (Decentralized Apps) in isolation from the real Ethereum blockchain.

Dictionary

What is Homebrew?

Homebrew installs the stuff you need that Apple didn’t. I’m not kidding, that’s what their website says. Go & check it out, it’s awesome.

What is Ethereum?

Ethereum is a cutting edge blockchain-based distributed computing platform, featuring smart contract functionality. It provides a decentralized virtual machine, the Ethereum Virtual Machine (EVM), that can execute peer-to-peer contracts using a crypto-fuel called Ether.

Read the white paper here.

What is Geth?

geth is the the command line interface for running a full ethereum node implemented in Go. It is the main deliverable of the Frontier Release.

By installing and running geth, you can take part in the ethereum live network, mine ether on the blockchain, transfer funds between addresses, create contracts and send transactions.

Tutorial

How to install Homebrew

If you haven’t done so yet, fire up your Terminal and start off by installing Homebrew:

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

If you’ve already installed Homebrew previously, make sure it’s up to date:

$ brew update
$ brew upgrade

How to install Geth

The easiest way to install Geth (go-ethereum) is to use the Homebrew tap

$ brew tap ethereum/ethereum 
$ brew install ethereum

Test if the installation was successful by running

$ geth version

This should display your currently installed Geth version:

Geth
Version: 1.6.7-stable
Git Commit: ab5646c532292b51e319f290afccf6a44f874372
Architecture: amd64
Protocol Versions: [63 62]
Network Id: 1
Go Version: go1.8.3
Operating System: darwin
GOPATH=
GOROOT=/usr/local/Cellar/go/1.8.3/libexec

As you can see, we’re currently running Geth version 1.6.7. Make sure to check the different options and commands with geth --help as well!

Let’s get dangerous

Connecting to the test net

Let’s start by creating a genesis block for your private testnet blockchain. The genesis block is the start of the blockchain — the first block, block 0, and the only block that does not point to a predecessor block. The protocol ensures that no other node will agree with your version of the blockchain unless they have the same genesis block, so you can make as many private testnet blockchains as you’d like! (See documentation)

Create & save a *.json file called CustomGenesis.json and put these contents in it:

{
    "config": {
        "chainId": 15,
        "homesteadBlock": 0,
        "eip155Block": 0,
        "eip158Block": 0
    },
    "difficulty": "0x400",
    "gasLimit": "0x2100000",
    "alloc": {
        "93f932b3b87e08cdaf0877994e44feb4c93e81aa": 
         { "balance": "0x1337000000000000000000" }     
    }
}

The file acts as a ‘seed’ for your private testnet.

Notice that we added our account address 93f932b3b87e08cdaf0877994e44feb4c93e81aa to the "alloc" object, and that we gave it a balance of 1337000000000000000000 wei (1337 ETH).

You can use this technique to pre-fund your account. You can define multiple accounts to include in the seed. Note that this step is optional, as you can easily mine the Ether yourself, as you’re in control of the (low) difficulty!

You will reference this file (CustomGenesis.json) when initialising your genesis block using the following command:

$ geth --identity "MyTestNetNode" --nodiscover --networkid 1999 --datadir /path/to/test-net-blockchain  init /path/to/CustomGenesis.json

To learn more about the other flags used, please navigate to the documentation.

Creating an account on the private tesnet

Create or find a directory where you’d like to store your local private testnet data. For this example, we’ll be using

$ /path/to/test-net-blockchain

After the previous geth --version command ran successfully, run

$ geth account new --datadir /path/to/test-net-blockchain

This command will ask you for a passphrase (=password). Do not forget this.

This will create an account on your fresh testnet node, and will return the private testnet address like so:

$ Address: {93f932b3b87e08cdaf0877994e44feb4c93e81aa}

Save this address and your password for later use.

Pre funding your account

This is an optional step. As the difficulty is so low, it would only take you a few minutes to mine enough Ether to get you going.

Start by removing your previously created blockchain database:

$ geth removedb --datadir /path/to/test-net-blockchain

Update your CustomGenesis.json file:

{
    "config": {
        "chainId": 15,
        "homesteadBlock": 0,
        "eip155Block": 0,
        "eip158Block": 0
    },
    "difficulty": "0x400",
    "gasLimit": "0x2100000",
    "alloc": {
        "93f932b3b87e08cdaf0877994e44feb4c93e81aa": 
         { "balance": "0x1337000000000000000000" }     
    }
}

Notice that we added our account address 93f932b3b87e08cdaf0877994e44feb4c93e81aa to the "alloc" object, and that we gave it a balance of 1337000000000000000000 wei (1337 ETH):

You can define multiple accounts to include in the seed.

Run the Genesis block initialisation command again

$ geth --identity "MyTestNetNode" --nodiscover --networkid 1999 --datadir /path/to/test-net-blockchain  init /path/to/CustomGenesis.json

If you haven’t done the prefunding

Use this command after starting the JavaScript Console (see next step: ‘Interact with Geth console’):

$ geth --identity "MyTestNetNode" --datadir /path/to/test-net-blockchain --nodiscover --networkid 1999 console

Interact with Geth console

To interact with Geth through the console, called the Geth JavaScript Console use:

$ geth --identity "MyTestNetNode" --datadir /path/to/test-net-blockchain --nodiscover --networkid 1999 console

If it ran successfully, you should see a confirmation:

If you see this message you can start running Geth JavaScript commands. Try to use this one to check the balance of your primary account

$ web3.fromWei(eth.getBalance(eth.accounts[0]), "ether")

Folder Structure

Purely informational, this is what my folder structure looks like:

As you can see, I created some *.sh script to re-use later on. I’ve created a repository as a reference.

Congratulations!

You now have a functioning private Ethereum testnet blockchain and an account/wallet running on your personal computer. You can now start mining, send transactions, etc. I’ll be writing some new articles regarding these topics in the near future.

Useful commands/tips

• - geth removedb Deletes/removes your locally synced blockchain data of the public testnet.
• - geth removedb --datadir /path/to/test-net-blockchain Deletes/removes your private blockchain testnet data.
• - geth --fast --cache=1024 Synchronises the blockchain more quickly. If you choose to use the — fast flag to perform an Ethereum fast sync, you will not retain past transaction data.
• - When using geth attach when running a private testnet, be sure to include the IPC endpoint. The IPC endpoint is shown when starting your Geth JavaScript console as such: IPC endpoint opened: /path/to/endpoint/geth.ipc Attach the path to your command so it becomes: geth attach /path/to/endpoint/geth.ipc

Useful commands/tips

Use these commands once your logged into the Geth console.

• - If you receive an error saying‘Error: authentication needed: password or unlock, use this command to unlock your primary account in the Geth JavaScript console:

$ personal.unlockAccount(eth.coinbase, 'your account password in quotes', 0)

• - To check the balance of your primary account

$ web3.fromWei(eth.getBalance(eth.accounts[0]), "ether")

• - To see a list of pending transactions

$ eth.pendingTransactions

Useful links

• - Ethereum docs
• - Geth JavaScript Console Wiki
• - Etherscan — An Ethereum Block Explorer and Analytics Platform
• - Ethereum Network stats monitor
• - https://github.com/WWWillems/medium-attachments/tree/master/01-private-ethereum-testnet

Useful commands/tips

People

• - Vitalik Buterin
• - Joseph Lubin

Resources

• - Ethereum docs
• - https://github.com/ethereum/go-ethereum/wiki/Installation-Instructions-for-Mac

Thanks for reading!

I’d love to hear from you and know what you think. Please let me know if you think anything’s missing. If you’d like to keep in touch, respond to this post below, follow me on Twitter or sign up to the newsletter using the form below.