Building and Operating a Private Ethereum Blockchain

This guide provides a comprehensive walkthrough for setting up a private Ethereum blockchain using the Go-Ethereum (Geth) client. It covers installation, network initialization, account management, transaction processing, and basic operations within a controlled development environment.

Installing the Geth Client

The first step is to install the Geth client, the official Go implementation of an Ethereum node. The process involves cloning the source code from its official repository and compiling it.

git clone https://github.com/ethereum/go-ethereum.git
cd go-ethereum
make geth

Upon successful compilation, the system will output a message indicating the path to the launchable geth binary. This confirms that the client is ready for use.

Configuring and Launching a Private Chain

A private blockchain is ideal for development and testing, as it operates in isolation from the public Ethereum networks.

Creating the Working Directory

Organize your project by creating a dedicated directory structure.

mkdir geth
cd geth
mkdir db
touch genesis.json

Defining the Genesis Block

The genesis.json file is the blueprint for your blockchain's first block. The following configuration is a common starting point for private chains due to its low mining difficulty.

{
 "config": {
 "chainId": 15,
 "homesteadBlock": 0,
 "eip155Block": 0,
 "eip158Block": 0
 },
 "coinbase" : "0x0000000000000000000000000000000000000000",
 "difficulty" : "0x40000",
 "extraData" : "",
 "gasLimit" : "0xffffffff",
 "nonce" : "0x0000000000000042",
 "mixhash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
 "parentHash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
 "timestamp" : "0x00",
 "alloc": { }
}

Key parameters include chainId, a unique identifier for your network, and difficulty, which controls how hard it is to mine new blocks. A lower value is suitable for CPU mining on a private net.

Initializing the Blockchain

With the genesis file defined, you can initialize your blockchain. This command creates the necessary data structures.

geth --datadir "./db" init genesis.json

This process generates the geth and keystore directories within your db folder, which will store all chain and account data, respectively.

Starting the Private Node

Launch your node with the following command. The --nodiscover flag prevents other nodes from automatically discovering and connecting to your network.

geth --datadir "./db" --nodiscover console 2>> geth.log

This command starts the node and opens an interactive JavaScript console, providing access to the web3 object and other management APIs. Logs are simultaneously written to geth.log for debugging purposes.

Performing Basic Operations

Once your node is running, you can interact with your private blockchain through the console.

Account Management

Accounts are essential for holding funds and executing transactions. You can create new accounts and view existing ones.

// Create a new account with a password
personal.newAccount("your_password")

// List all accounts on the node
eth.accounts

New accounts start with a zero balance. Account files are stored in the keystore directory and are encrypted with the password you provided.

Checking Balances

You can check the balance of any account. Balances are returned in wei, the smallest denomination of Ether.

eth.getBalance(eth.accounts[0])

Mining and Block Generation

Mining is the process of creating new blocks and securing the network. On a private chain, you can start and stop mining at will.

// Set the account that receives mining rewards
miner.setEtherbase(eth.accounts[0])

// Start mining with one thread
miner.start(1)

// Stop mining
miner.stop()

👉 Explore more strategies for efficient blockchain testing

Executing Transactions

To transfer value between accounts, you must send a transaction. The sending account must be unlocked first.

// Unlock the sender account for 300 seconds
personal.unlockAccount(eth.accounts[0], "password", 300)

// Send 1 Ether from accounts[0] to accounts[1]
eth.sendTransaction({from: eth.accounts[0], to: eth.accounts[1], value: web3.toWei(1, "ether")})

For the transaction to be finalized and written to the blockchain, it must be included in a mined block. You can check the transaction pool status with txpool.status. After mining a block, you can verify the new balances and view transaction details using eth.getTransaction() and eth.getTransactionReceipt() with the transaction hash.

Frequently Asked Questions

Why does miner.start() sometimes return null and not mine?
This behavior, especially in --dev mode, is often due to the default dev.period setting. A value of 0 means the miner will only create a block if there is a pending transaction. To enable continuous mining in dev mode, launch your node with the flag --dev.period 1.

What is gas and why is it deducted from my account?
Gas is the unit that measures the computational effort required to execute operations, like transactions or smart contracts, on the Ethereum Virtual Machine (EVM). You pay for gas to compensate miners for the resources (CPU, memory) they expend to process your request. The total cost is gasUsed * gasPrice.

My transaction is 'pending'. What does this mean?
A pending transaction has been broadcast to the network but has not yet been included in a block by a miner. This is normal. The transaction will be confirmed once a miner includes it in the next block they mine. You can speed this up on a private chain by simply starting your miner.

How do I connect two separate private nodes together?
You can form a private network by ensuring both nodes use the identical genesis.json file and the same networkid. Use admin.nodeInfo.enode on one node to get its connection string, then use admin.addPeer("enode://...") on the other node to connect them.

Where are my account files stored?
Account keyfiles are stored in the keystore directory within your specified datadir (e.g., ./db/keystore/). These files are encrypted with the password you created them with. It is crucial to back up this entire directory.

What is the JavaScript console I'm using?
The console is a interactive environment that provides access to the full Geth JavaScript API. This includes the eth, personal, miner, and admin namespaces, allowing you to manage your node, accounts, and interact with the blockchain directly. You can also attach to a running node's console later using geth attach ipc:path/to/geth.ipc.