How to Run Your Own Private Ethereum Blockchain

This article is part of the series about developing decentralized applications and your own crypto tokens and cryptocurrencies. In this part, we'll cover how to best get started with your own private blockchain, how to run commands on it, and how to mine on it.

This article will have no code – we will only set up a good starting infrastructure.

To have an easier time following along, it is recommended (but not obligatory) to read the following material:

• What is the blockchain?
• What is Ethereum and how is it different from Bitcoin?
• My first Ethereum address with MyEtherWallet
• What are nodes?
• Ethereum Terminology: What is Mist, and what is Geth?

This article will require you to run certain commands from the terminal – a special program present on every operating system and used to execute commands without a graphical interface. Some commands are only accessible that way.

On OS X and Linux operating systems, that program is built-in and is called Terminal – you can find it by simply searching your system. On Windows, there is the Command Prompt (CMD), also findable in simple search, or the Shell Terminal. The best version of Shell called Git Bash can be downloaded by installing Git Tools. Alternatively, newer versions of Windows have the Linux Subsystem which lets you use a whole Linux system inside of Windows.

Introduction

Whenever you're starting a new application or project on the Ethereum blockchain, it's good to have a test environment on which to deploy your application for free so that you can properly break it and find its holes. Apart from using testnets where you need to obtain fake Ether and be connected to the internet, a good option is running your own private blockchain – either via a simulation like testrpc, or through your own private blockchain.

The private blockchain approach is the one we'll be taking here.

testrpc, like most NodeJS software packages, has some bugs which aren't currently resolvable so it'll be covered in a future post.

Prerequisites

For starters, you need:

• some disk space. Up to a few GB will be enough. If you intend to keep a real full node running (connected to the public blockchain), you'll need a hundred GB or so. It is recommended to keep this data on an external hard drive, like a big portable USB drive, because this keeps your own drive clean, while making your work highly portable between machines and other developers.
• download and install geth.
• download and install mist. Pick the “Mist” file, not the “Ethereum-Wallet-Installer” file, and pick the one appropriate for your system: .dmg for OS X, exe for Windows, deb on Linux.

If you don't know what Geth and Mist are, please read this introduction.

Note that if you're using an external hard drive with OS X for this, you MUST format it to OS X Extended Journaled. It must not be MS-DOS formatted.

Genesis

Every blockchain has its genesis, its beginning. To make your own blockchain, you need to create a genesis.json file in the folder where you intend to keep the private blockchain data, like on an external hard drive. In our case and in the examples below, the location will be /Users/swader/blockchain/tutorial.

Put the following content into the genesis.json file once you place it into that folder:

{
    "config": {
        "chainId": 987,
        "homesteadBlock": 0,
        "eip155Block": 0,
        "eip158Block": 0
    },
    "difficulty": "0x400",
    "gasLimit": "0x8000000",
    "alloc": {}
}

This file defines certain attributes of our blockchain like:

• chainId: network identifier. Can be a random number. Used to identify the chain on the network our node is running on. One network can host several blockchains and this is used to differentiate between them.
• homesteadBlock: necessary if you're starting from an existing block in the Homestead version of Ethereum. 0 is OK in this case. You will rarely need to change this, if ever.
• EIP blocks: necessary to define if the plan is to activate the chain at a specific software version – EIPs are Ethereum Improvement Proposals, so activating them at certain EIP blocks means you choose that specific version. Same as above, not needed and can be left at 0.
• difficulty indicates how fast blocks will be mined. The lower it is (this setting is pretty low), the faster blocks will confirm and transactions will be processed.
• gasLimit: explained in detail in this post, but the gist of it is that this sets the maximum cost of transactions. It's important for this to be high so you can debug extra-expensive transactions and optimize them.
• alloc: short for allocate, lets us define some addresses with their starting amount of Ether. These don't have to wait for Ether to be mined then. Unnecessary, we'll mine our own.

In order for geth to take the genesis file into account and create a new chain from it, the following command needs to be executed:

geth --datadir /Users/swader/blockchain/tutorial init /Users/swader/blockchain/tutorial/genesis.json

init means “initialize” while datadir tells geth where to save block data. The blockchain is now ready for activation with the following command:

geth --datadir /Users/swader/blockchain/tutorial --networkid 987 --rpc --rpccorsdomain "*" --rpcapi "db,eth,net,web3,personal"

This command has started our own geth node in the datadir we defined earlier. We also pointed the node towards the right network ID: 987, and told it to allow connections via the RPC protocol using the rpccorsdomain option (this further lets us connect to our node with Mist and Metamask). We also activated the following program interfaces in the node: db, eth, net, web3, personal. Each of these has its own context and purpose. For example, personal lets us manage our personal accounts that live on our node though external applications which connect to the node via RPC. In other words, this lets the Mist or MetaMask app send transactions for us.

The terminal application's screen should have printed out something like this after the last command:

Brunos-MBP:tutorial swader$ geth --datadir . --networkid 987 --rpc --rpccorsdomain "*" --rpcapi "db,eth,net,web3,personal"
INFO [01-23|21:46:22] Starting peer-to-peer node               instance=Geth/v1.7.3-stable/darwin-amd64/go1.9.2
INFO [01-23|21:46:22] Allocated cache and file handles         database=/Users/swader/blockchain/tutorial/geth/chaindata cache=128 handles=1024
INFO [01-23|21:46:22] Initialised chain configuration          config="{ChainID: 987 Homestead: 0 DAO:  DAOSupport: false EIP150:  EIP155: 0 EIP158: 0 Byzantium:  Engine: unknown}"
INFO [01-23|21:46:22] Disk storage enabled for ethash caches   dir=/Users/swader/blockchain/tutorial/geth/ethash count=3
INFO [01-23|21:46:22] Disk storage enabled for ethash DAGs     dir=/Users/swader/.ethash                                 count=2
INFO [01-23|21:46:22] Initialising Ethereum protocol           versions="[63 62]" network=987
INFO [01-23|21:46:22] Starting P2P networking
INFO [01-23|21:46:24] UDP listener up                          self=enode://be8572fae08d5a3bf01e065891f4fa3ddea4951afdd1535bae55c8e2367acbf8722accf140dd73f93238265efbccd2b26bf9b8b651c27e85783ffb6a5503e017@[::]:30303
INFO [01-23|21:46:24] RLPx listener up                         self=enode://be8572fae08d5a3bf01e065891f4fa3ddea4951afdd1535bae55c8e2367acbf8722accf140dd73f93238265efbccd2b26bf9b8b651c27e85783ffb6a5503e017@[::]:30303
INFO [01-23|21:46:24] IPC endpoint opened: /Users/swader/blockchain/tutorial/geth.ipc
INFO [01-23|21:46:24] HTTP endpoint opened: http://127.0.0.1:8545

The Geth Console

It's time to connect to the active geth node we're running. Open a new Terminal window (the current window is still running geth from the previous step and needs to stay alive), and run the command:

geth attach /Users/swader/blockchain/tutorial/geth.ipc

The path to geth.ipc can vary depending on the folder you've picked for your datadir in step 1. The real path will be printed on screen once you run the previous command, at the very end, under IPC endpoint opened.

We're now in the interactive environment of the geth node, also known as the geth console.

Every geth environment automatically includes a Web3 interface which you can use to easily communicate with the blockchain and the Ethereum protocol in general.

Web3 is a set of software commands which lets websites talk to the blockchain. In the context of Geth, Web3 makes it possible to execute commands which would be generally far too difficult or counterintuitive to execute without it.

For example, if we type in eth while in the console, we'll get a list of commands available from within the global eth command provided by Web3 (if you don't know what this means, it doesn't matter in the context of this post).

Coinbase

For a node to be functional, it needs a coinbase address. That address is the address which will receive ether mined on that node and has nothing to do with the exchange of the same name. When setting up a new node, the coinbase address is empty and undefined and needs to be created. You can see this by running eth.coinbase. To make a new one, run:

personal.newAccount("password")

replace password with a password you'll use to unlock these wallets. Don't forget it, if you do, all mined ether will be lost.

When running eth.coinbase subsequently, it will show a value.

Mining

You can check how much ether an address has by running the eth.getBalance command which accepts an address as a parameter. Let's check the balance of the newly created coinbase address:

When sending a transaction in order to send Ether, send tokens, or run a decentralized application, it's necessary to mine that transaction in order for it to be confirmed and included into the blockchain. This is also the only way for the coinbase account to get some ether, other than by sending directly to it. It's very easy to run private mining. Just type miner.start(1) into the console, let it run for a while, then run miner.stop(). During miner.start‘s running time the previous terminal screen which is still running Geth will show signs of life:

After mining has been on for a while, the balance of the coinbase account will have changed:

The balance is shown in wei, the smallest possible Ethereum blockchain's unit. To get the ether balance (in this case 225) it's necessary to divide by 10^18 or to run the command web3.fromWei with eth.getBalance(eth.coinbase) as the argument:

Note: miner.start can accept a whole number (integer) as an argument, like so: miner.start(1). This number is the number of processor cores to use for mining. More cores means faster mining but also more work (and power, and heat) for your computer. For development purposes with a low difficulty in the genesis file, even a single core is usually fast enough to be almost instant.

When mining for the first time, geth needs some time to generate a DAG – around 60 seconds. Let it finish and it will continue as planned on its own. The DAG is a set of information which is needed for ether mining, explained in more detail in this technical paper.

Conclusion

Running your own blockchain for development, experimentation and learning is very easy. Ether is easy to mine in a private environment and this approach is very appropriate for not only fearless programming but also for measuring how much gas your transactions will cost exactly.

In the next article, we'll cover how to add new nodes into the network to create a full multi-miner blockchain, and how to connect MyEtherWallet, Mist, and MetaMask to our private blockchain.

Also, this and much more will also be covered at the coming Blocksplit conference.

If you found this article useful or interesting, please consider donating to keep our operation running.