How to Build a Private Ethereum Blockchain with Geth

·

Blockchain technology, particularly public chains, has gained significant traction. However, for use cases requiring data privacy and controlled access, a private, managed blockchain is essential. This guide provides a comprehensive walkthrough for setting up a private Ethereum test network using Geth, the official Go implementation of the Ethereum protocol.

Prerequisites and Initial Setup

Before diving into the private chain setup, ensure you have the necessary tools and environment configured.

Installing Go and Building Geth from Source

Building from source is recommended for greater control and customization. Start by installing the Go programming language.

Download the Go installation package, extract it, and configure the environment variables:

export GO_HOME=/path/to/your/go/directory
export PATH=${JAVA_HOME}/bin:${GO_HOME}/bin:$PATH

Next, clone the go-ethereum repository from GitHub:

git clone https://github.com/ethereum/go-ethereum

Building Geth requires both Go and C compilers. Install the essential build tools on Ubuntu:

sudo apt-get install -y build-essential

Finally, navigate to the cloned directory and build Geth:

cd go-ethereum
make geth

The compiled geth binary will be located in the build/bin directory. Add this to your PATH for easy access:

export GETH_HOME=/path/to/go-ethereum/build
export PATH=${GO_HOME}/bin:${GETH_HOME}/bin:$PATH

Verify the installation by running:

geth version

Building Your Private Testnet

A private Ethereum network allows you to control the nodes, consensus, and data, making it ideal for development, testing, and private business applications.

Creating Initial Accounts

The first step is to create user accounts that will hold the initial balance of Ether on your private chain.

Create a new account using the following command. You will be prompted to set a password.

geth --datadir /path/to/your/data/directory account new

Upon successful creation, the command outputs the public address and the path to the encrypted key file. Repeat this process to create at least three accounts for testing purposes.

List all accounts in your keystore to confirm their creation:

geth account list --keystore /path/to/your/data/keystore

Defining the Genesis Block

The genesis block is the first block of your blockchain. Its parameters define the fundamental rules of your network. Create a JSON file, CustomGenesis.json, with the following structure:

{
  "config": {
    "chainId": 3131,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip155Block": 0,
    "eip158Block": 0
  },
  "difficulty": "10000",
  "gasLimit": "2100000",
  "alloc": {
    "0xYourFirstAccountAddress": { "balance": "800" },
    "0xYourSecondAccountAddress": { "balance": "600" },
    "0xYourThirdAccountAddress": { "balance": "800" }
  }
}

Key Parameters Explained:

Initializing the Genesis Block

Initialize your blockchain data directory with the custom genesis block configuration:

geth --datadir /path/to/your/data/directory init /path/to/CustomGenesis.json

This command creates the necessary chaindata and initializes the state with the pre-allocated balances.

Starting the Private Network Node

Launch your first node with the following command. The parameters customize the node's behavior for a private network.

geth --identity "ETH-MainNode" \
     --rpc \
     --rpcport "6060" \
     --rpccorsdomain "*" \
     --datadir "/path/to/your/data/directory" \
     --port "30303" \
     --maxpeers 5 \
     --rpcapi "admin,db,eth,debug,miner,net,shh,txpool,personal,web3" \
     --networkid 3131 \
     --allow-insecure-unlock \
     console

Key Flags Explained:

Once inside the console, verify the initial balances of your accounts:

> eth.getBalance("0xYourFirstAccountAddress")
800

Adding Peer Nodes

A multi-node network is more representative of a real blockchain. To add a peer, start a second node on a different machine or port with a unique --identity but the same --datadir, --networkid, and genesis configuration.

On the first node (MainNode), retrieve its enode URL:

> admin.nodeInfo.enode
"enode://...@[::]:30303?discport=0"

Note the IP address (replace [::] with the node's actual IP, e.g., 192.168.1.10).

On the second node (SlaveNode), inside its console, add the main node as a peer:

> admin.addPeer("enode://[email protected]:30303")
true

Verify the connection was successful:

> net.peerCount
1
> admin.peers
[...] // Should show details of the connected peer

Testing the Private Ethereum Chain

With your network running, you can test its core functionality: mining and transactions.

Mining Blocks

Create a new account on each node to use as an Etherbase (mining reward address).

On the main node:

> personal.newAccount()
// Set password, note the address
> miner.setEtherbase("0xYourNewMainNodeAccount")
true
> miner.start(1) // Start mining with 1 thread

On the slave node:

> personal.newAccount()
// Set password, note the address
> miner.setEtherbase("0xYourNewSlaveNodeAccount")
true
> miner.start(1)

After a period, you will see messages indicating blocks are being mined. Check the balance of your miner accounts; it should have increased significantly due to the block rewards and included transaction fees.

> eth.getBalance("0xYourNewMainNodeAccount")
5.8871875e+21
> miner.stop() // Stop mining when done

Executing a Transaction

Let's test sending Ether between accounts. First, create a new account to receive funds.

> personal.newAccount()
"0xReceiverAccountAddress"

Unlock the sender's account (the miner account with a large balance):

> personal.unlockAccount("0xYourNewMainNodeAccount")
// Enter password
true

Send a transaction of 2 Ether:

> eth.sendTransaction({from: "0xYourNewMainNodeAccount", to: "0xReceiverAccountAddress", value: web3.toWei(2, "ether")})
"0xtransactionHash"

Initially, the receiver's balance will be zero because the transaction is only in the mempool, not yet in a block. To include it in the blockchain, start the miner again:

> miner.start(1)
// Wait for a block to be mined...
> miner.stop()

Now, check the receiver's balance:

> eth.getBalance("0xReceiverAccountAddress")
2000000000000000000 // 2 Ether in Wei

You can also query the transaction details using its hash:

> eth.getTransaction("0xtransactionHash")

Verify this transaction and the resulting balance on the slave node to confirm the blockchain state is synchronized across peers.

👉 Explore more blockchain development strategies

Frequently Asked Questions

Q: Why build Geth from source instead of using a package manager?
A: While package managers are easier, they can often lag behind the latest version and might have missing dependencies or conflicts. Building from source ensures you get the most recent features and fixes and allows for a more customized installation.

Q: What is the purpose of the alloc section in the genesis file?
A: The alloc (allocation) section pre-funds specified accounts with an initial balance of Ether at the genesis block. This is crucial for testing, as it provides accounts with the funds needed to pay for gas and execute transactions without needing to mine first.

Q: Why can't my nodes discover each other automatically?
A: We use the --nodiscover flag (implied in our setup) to prevent the node from being discovered by the public Ethereum network. In a private network, peers must be added manually using admin.addPeer() to ensure only authorized nodes join.

Q: I get an 'insufficient funds' error when trying to send a transaction. Why?
A: This error means the sending account's balance is less than the value of the transaction plus the gas fee (gasLimit * gasPrice). Ensure the account has enough Ether. If using a pre-funded genesis account, a known bug sometimes causes rounding issues; try sending from a miner account that has earned block rewards instead.

Q: What does 'account unlock with HTTP access is forbidden' mean?
A: This is a security feature to prevent unauthorized remote unlocking. For private testnets, you can override it by adding the --allow-insecure-unlock flag to your startup command. Never use this flag on a mainnet or public node.

Q: How can I reset my blockchain and start over?
A: To completely reset, stop your Geth node and delete the contents of your datadir directory (especially the geth/ and history subfolders). Re-run the geth init command with your genesis file to start with a fresh state.

Summary

This guide detailed the process of building a private Ethereum testnet using Geth compiled from source. We covered creating initial accounts, defining a custom genesis block, initializing and starting the network, connecting multiple peer nodes, and testing core functionalities like mining and transactions.

Key takeaways include the importance of consistent configuration across all nodes (especially chainId), the need to pre-create accounts before allocating funds in the genesis block, and the security considerations around account unlocking. Private blockchains are powerful tools for development and prototyping, offering a sandboxed environment to learn and build upon Ethereum's technology.