Building the Geth Network

Step 1.1: Get Geth.

Just follow the official install guide for your OS.

Step 1.2: Create a signer account.

We'll be using PoA, so you need an authorized signer node to mint and sign the blocks. The first step is creating a signer account which the signing node will use to sign blocks (the PoW equivalent of PoA):

geth account new --datadir data1

the account generator will ask you to set a password (you can leave blank), and then will print the account ID:

INFO [03-22|12:58:05.637] Maximum peer count                       ETH=50 total=50
INFO [03-22|12:58:05.638] Smartcard socket not found, disabling    err="stat /run/pcscd/pcscd.comm: no such file or directory"
Your new account is locked with a password. Please give a password. Do not forget this password.
Password: 
Repeat password: 

Your new key was generated

Public address of the key:   0x93976895c4939d99837C8e0E1779787718EF8368
...

the keys will be stored under ./data1/keystore. You should keep the account ID stored somewhere as you will need it later. It is also probably a good idea to create a few more accounts to use with the Codex clients. You can repeat the command above a few more times; make sure to write down the account ids.

Step 1.3: Create the configuration for the network.

With a few accounts in hands, we are ready to create the configuration file for our network. This configuration file defines things like:

  • the type of consensus algorithm used in the network;
  • the historical version of Ethereum you want to run and when, including the hability to pre-program historical hard forks and toggle new features as certain block heights are reached;
  • the initial set of accounts in the network, and the initial amount of ETH for each account;
  • transaction gas limits.

Note that this can get confusing pretty quickly. In particular, the fact that you can replay Ethereum upgrades at specific block heights (or timestamps, in case of Shanghai) can be very confusing, as can the fact that certain features will work only with certain Ethereum versions and not with others, and the only indication you will get that something stopped working is a message that gets quickly buried in logs. Missing parameters will furthermore often simply cause a feature not to work and will not generate errors [1]. All of this can contribute to puzzling and surprising behavior.

With that in mind, we create a configuration file named network.json which specifies a pre-merge PoA network based on Gray Glacier, which was the last Ethereum upgrade before the merge:

{
  "config": {
    "chainId": 12345,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "berlinBlock": 0,
    "londonBlock": 0,
    "arrowGlacierBlock": 0,
    "grayGlacierBlock": 0,
    "clique": {
      "period": 1,
      "epoch": 30000
    }
  },
  "difficulty": "1",
  "gasLimit": "8000000",
  "extradata": "0x000000000000000000000000000000000000000000000000000000000000000093976895c4939d99837C8e0E1779787718EF83680000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "alloc": {
    "93976895c4939d99837C8e0E1779787718EF8368": { 
      "balance": "10000000000000000000000"   
    }
  }
}

Note that the *Block parameters are all set to zero, which means we will be at Gray Glacier at block heights \(\geq\) 0. Also note that the account we created in Step 2 (0x93976895c4939d99837C8e0E1779787718EF8368) is embedded in the extradata string, as well as assigned a balance under alloc – make sure to replace it with the signer account ID you created before. Any other accounts you may have created can also have balances assigned to them here under separate entries in alloc.

Also note the configuration for the PoA consensus algorithm, Clique:

"clique": {
  "period": 1,
  "epoch": 30000
}

this tells that the network should pump out a block at every \(1\) seconds (you will undertsand why we want such a short period in Step 2.2), and that the maximum window for a running signer membership ballot (which we do not really care about as our signer network is static) is \(30\,000\) blocks[2].

Step 1.4: Initialize the network.

We can now create the genesis block for the network and set up geth. We initialize this under data1 as the first node in our network will also be the signer:

geth init --datadir data1 network.json

Step 1.5: Launch the initial node.

To launch the initial node, run:












geth\ 
  --datadir data1\
  --networkid 12345\
  --unlock 0x93976895c4939d99837C8e0E1779787718EF8368\
  --password <your-accounts-password>\
  --nat extip:127.0.0.1\
  --netrestrict 127.0.0.0/24\
  --mine\
  --miner.etherbase 0x93976895c4939d99837C8e0E1779787718EF8368\
  --http\
  --allow-insecure-unlock

This will launch a geth node using account 0x93976895c4939d99837C8e0E1779787718EF8368 to sign blocks (--miner.etherbase). This means we need to allow geth to unlock the account; i.e., read its private key, which we do through --unlock and --password. Note that we are also enabling JSON-RPC access in this node (with --http), which means any transactions submitted to it will be automatically signed. Since this is highly unsafe (it could allow one to drain the balance of the unlocked account), we also need to pass --allow-insecure-unlock[3].

Finally, we set --nat extip:127.0.0.1 so that the node allows other nodes to boostrap from it. By default, geth will try to connect to peers in every network it knows about, so it is probably a good idea to constrain connections to the local network only. This is done with the --netrestrict 127.0.0.0/24 option.

Step 1.6: Launch the second node.

As before, we need to initialize the second node so it knows about our network:

geth init --datadir data2 network.json

Now recall that the first node will be our bootstrap node. We therefore first need to obtain its ENR (Ethereum Name Record), which is similar to libp2p SPRs. To do that, we can use the geth console. This will go something like:

➜  geth geth attach --exec admin.nodeInfo.enr ./data1/geth.ipc
"enr:-KO4QF8ztLpqqery6xLqcL8bvsQqTQPi4Si07Hg3mascRl0LLUIAPLBM3aF-LHnAyjWO4M-g44gzJ715Wg30kTKuDVmGAY5n3QuLg2V0aMfGhBpX1EaAgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQMtJholIyJHLn9atGa5ECgyLdlJ5bVfDJwxowUvtDza24RzbmFwwIN0Y3CCdl-DdWRwgnZf"

we can then use that ENR to boostrap our node:









geth\
  --datadir data2\
  --networkid 12345\
  --bootnodes "enr:-KO4QF8ztLpqqery6xLqcL8bvsQqTQPi4Si07Hg3mascRl0LLUIAPLBM3aF-LHnAyjWO4M-g44gzJ715Wg30kTKuDVmGAY5n3QuLg2V0aMfGhBpX1EaAgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQMtJholIyJHLn9atGa5ECgyLdlJ5bVfDJwxowUvtDza24RzbmFwwIN0Y3CCdl-DdWRwgnZf"\
  --port 30305\
  --authrpc.port 8036\
  --http\
  --http.port 8546

where --port, --authrpc.port, and --http.port are specified to avoid clashes with the first node use of the default ports. Since this is not a miner node, it does not need to unlock any accounts.

Deploying Codex Contracts

We are finally ready to deploy Codex's contracts.

Step 2.1. Clone the Codex ETH contracts repo and install deps.




git clone https://github.com/codex-storage/codex-contracts-eth
cd codex-contracts-eth
npm install

Step 2.2. Wait for \(256\) blocks to be mined.

You need to wait for a block height of \(256\) to be reached in the network before you can deploy the contracts. You can inspect that in node 2, for fun:

geth attach --exec web3.eth.blockNumber ./data2/geth.ipc

once that prints something \(\geq 256\), you are good to go.

Step 2.3. Deploy contracts.

To deploy contracts, we can simply reuse the deploy configuration for the distributed tests and set the URL to the bootstrap node. Note that although the non-bootstrap node should also in theory allow contracts to be deployed, I was not able to make that work[3:1].



export DISTTEST_NETWORK_URL=http://localhost:8545 # bootstrap node
npx hardhat --network codexdisttestnetwork deploy

Once the command returns, you're done.

Github Repo

I have put together the code for this tutorial in a github repo for reference. It includes a script to launch it all on Linux.

  1. One such example is trying to run the Shanghai EVM with Proof-of-Authority (PoA) consensus, which is a geth-specific consensus implementation. Because Shanghai networks have moved consensus into a separate consensus client, geth will simply cease to run consensus once the Shanghai timestamp is reached and expect a beacon client to be present. This is confusing because PoA has always been a geth-only construct, and yet they decided to drop support for it in epochs after the beacon chain split on the basis that having consensus built in would then become too much of a deviation from how "real Ethereum" works, and too much of a maintenance burden. ↩︎

  2. Clique PoA protocol & Rinkeby PoA testnet ↩︎

  3. Ideally we would not enable JSON-HTTP access in this node and have it enabled in the non-signer node instead. I could not get that to work, however – contract deploy transactions would simply get stuck in the txpool. We therefore keep it simple here, but feel free to try a better setup if you feel like it. ↩︎ ↩︎

Select a repo