Beginners guide to Ethereum (3) — explain the genesis file and use it to customize your blockchain


This tutorial serves as a complete guide that combines all the information you will need about a genesis file, including some of the ethereum history background for your better understanding:)

Important Notes before you start

Please be aware that the settings of the genesis file presented below may be outdated in the future if changes(hard forks) are made by the Ethereum Foundation. The tutorial below is to help developers have a better understanding through starting evrything from scratch. But you can always do this in a much more easier way: Use the official CLI that is automatically installed followed withgethcalled puppeth, which helps create and customize your genesis file. Simply type puppeth in your terminal window and you will be prompted to input the required parameters such as where should the file be saved at, which consensus to use(PoW or PoA), and which accounts should be prefunded. Here is a sample usage tutorial.

Great thanks to Lycrus Hamster for raising this issue!

What is a genesis file

The genesis block is the start of the blockchain, and the genesis.json is the file that defines it. It is like the “settings” for your blockchain. For example, the chain configuration, level of difficulty to mine blocks, etc.

It is optional. You can also use the — dev flag instead to use the pre-configured settings provided by geth.


There are 4 required value(config, difficulty, gasLimit, alloc) you need to specify in genesis.json. I’ve tried removing all of them and made sure all of them are required XD

Example genesis.json :

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

Params explain:

  1. “config”: The blockchain configuration.
  • “chainId”: protection of the replay attack(an unauthorized user acting as the original sender). For example, if an action is validated by matching certain value that depends on the chain id, attackers cannot easily get the same value with a different id. (A video about replay attack:
  • “homesteadBlock”: Homestead is the second major release of Ethereum(the first release is Frontier). The value 0 means that you are using this release.
  • “epi155Block”: epi stands for Ethereum Improvement Proposal, where developers propose ideas on how to improve Ethereum and contribute to this project.


2. “difficulty”: mining difficulty // set this value low so you don’t have to wait too long for mining blocks

3. “gasLimit”: the limit of gas cost per block // set this value high to avoid being limited when testing

4. “alloc”: pre-funded address, the first parameter of each is the address . Need to be a 40 digits hex string(160 bit, one hex digit is 4 bit). Note that this does not create an account

Start coding!

Hint: you can create a new folder and use it for testing

( mkdir "your_folder" then cd "your_folder" )

  1. create our genesis.json file
cat > genesis.json

Paste the example genesis.josn mentioned before.

Press Enterand then Ctrl+D to save and exit

2. Init our blockchain with the settings in the genesis file and define a folder for storing chain data

geth init genesis.json --datadir test

Note that you don’t need to create the “test” folder as geth will create it for you if it does not exist.

Also be careful that the command geth is different from geth init. Check this by appending — help flag like this:

geth --help
geth init --help // the two output is different

This means that you cannot use flags such as “ — networkid” in “geth init”.

3. Open a geth node with the geth console

geth --networkid 123 --datadir test console 
// remember the datadir has to be the same

But then you may notice there’s a warning in the output

WARN [07–05|17:36:27] No etherbase set and no accounts found as default

This is because the “alloc” parameter in the genesis file does not create any account. It is just an address with balance in it. For example in this case,


will output the exact value you set.

4. Start mining

If you start mining directly like this:miner.start() , the output would be

Error: etherbase missing: etherbase address must be explicitly specified

This is because geth will take the first account as the default coinbase account(where the mining rewards go to, required before mining), so the value is not specified as we don’t have any account now.

So first set the coinbase address (coinbase is the same as etherbase)

// you can also use arbitrary address as long as there are 40 digits

and then start mining


You should see the mining process going soon:)

If it stops in this line

Done generating DAG for epoch 0

It means that you set the mining difficulty(the “difficulty” parameter in genesis file) too high so you may have to wait longer.

Wrap up

After the three tutorial, you should have more experience with geth, have a taste of how blockchain is set up and how it can start mining. Hope you like it. I’m open to any suggestion. Thank you:)