IBFT Hyperledger Besu DevTest Lab Setup - SAABOLImpactVenture/enterprise-azure-governance-template-specs-deployment-stacks GitHub Wiki

# 🏗️ IBFT Hyperledger Besu DevTest Lab Setup

This page walks through how we scaffolded and locked-down an IBFT‐consensus Hyperledger Besu network in Azure DevTest Labs—versioning everything alongside our Bicep templates and wiring it into CI.

---

## 📋 Overview

We’ll cover:

1.  **Generating four validator keypairs & addresses**
2.  **Creating the `chainConfig.json` descriptor**
3.  **Running `besu operator generate-blockchain-config`** to emit:
    * `genesis.json` (with RLP-encoded `extraData`)
    * per-validator `nodekey-*.key` files
4.  **Cleaning up the `genesis/` folder**
5.  **Committing & wiring** the files into our DevTest Lab Bicep and install script

---

## 🔧 Prerequisites

* **Besu CLI** v25+ installed and on your `PATH`
* **Node.js** & **npm** (for our helper scripts)
* **ethers** library:
    ```bash
    npm install ethers
    ```
* A DevTest Lab deployed (or a feature branch ready to trigger the GitHub workflow)
* `devtest-lab/genesis/` folder under version control

### 1. Generate Validator Accounts

We create four random Ethereum keypairs and capture their addresses.

Save this as `scripts/genValidatorAccounts.js`:

```javascript
// scripts/genValidatorAccounts.js
const { Wallet } = require("ethers");
const fs = require("fs");
const path = require("path");

const outputDir = path.join(__dirname, "../devtest-lab/genesis/keys");
fs.mkdirSync(outputDir, { recursive: true });

const accounts = [];
for (let i = 1; i <= 4; i++) {
  const w = Wallet.createRandom();
  accounts.push({ validator:`validator-${i}`, address: w.address });
  fs.writeFileSync(path.join(outputDir, `validator-${i}.key`), w.privateKey);
}

fs.writeFileSync(
  path.join(outputDir, "validatorAccounts.json"),
  JSON.stringify(accounts, null, 2)
);

console.log("✅ Generated 4 validator keypairs in:", outputDir);

Run the script:

node scripts/genValidatorAccounts.js

Inspect

Four files:

devtest-lab/genesis/keys/validator-1.key
… validator-4.key
devtest-lab/genesis/keys/validatorAccounts.json

Copy the four address values from validatorAccounts.json for the next step.

2. Create chainConfig.json

Version your chain configuration for Besu’s operator:

// devtest-lab/genesis/chainConfig.json
{
  "chainId": 10,
  "networkId": 10,
  "ibft2": {
    "blockPeriodSeconds": 2,
    "epochLength": 30000,
    "requestTimeoutSeconds": 4
  },
  "gasLimit": "0x1C9C380",
  "difficulty": "0x1",
  "alloc": {
    "0xADDR1": { "balance": "0x1000000000000000000000000" },
    "0xADDR2": { "balance": "0x1000000000000000000000000" },
    "0xADDR3": { "balance": "0x1000000000000000000000000" },
    "0xADDR4": { "balance": "0x1000000000000000000000000" }
  },
  "validators": [
    "0xADDR1",
    "0xADDR2",
    "0xADDR3",
    "0xADDR4"
  ]
}

Replace 0xADDRn with the addresses from your manifest.

3. Generate the Locked-down genesis.json

Use Besu’s operator command to produce your genesis and nodekeys:

besu operator generate-blockchain-config \
  --config-file devtest-lab/genesis/chainConfig.json \
  --to          devtest-lab/genesis/output

The output folder devtest-lab/genesis/output/ will contain:

• genesis.json
• nodekey-validator-0
• nodekey-validator-1
• nodekey-validator-2
• nodekey-validator-3

4. Clean Up & Version

Move the artifacts into your repo and remove temp files:

# Move into versioned folders
mv devtest-lab/genesis/output/genesis.json   devtest-lab/genesis/genesis.json
mv devtest-lab/genesis/output/nodekey-* devtest-lab/genesis/keys/

# Clean up
rm -rf devtest-lab/genesis/output

# Stage & commit
git add devtest-lab/genesis
git commit -m "🔒 Lock down IBFT genesis.json with real validator addresses and nodekeys"
git push

Your final devtest-lab/genesis/ should look like:

genesis/
├── chainConfig.json
├── genesis.json
└── keys/
    ├ validator-1.key
    ├ validator-2.key
    ├ validator-3.key
    ├ validator-4.key
    └ validatorAccounts.json

5. Deploy & Validate

Dry-run your Bicep:

az deployment group validate \
  --resource-group $DEVTEST_LAB_RG \
  --template-file devtest-lab/blockchain-devtestlab-environment.bicep \
  --parameters @devtest-lab/parameters/blockchain-env.parameters.json

Trigger the Deploy Blockchain DevTest Lab GitHub Action.

Verify your four validator VMs, two RPC/API nodes, and two bootnodes come up and join the IBFT network.