proxmox/docs/06-besu/BESU_OFFICIAL_REFERENCE.md

# Hyperledger Besu Official Repository Reference

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**Source**: [Hyperledger Besu GitHub Repository](https://github.com/hyperledger/besu)  
**Documentation**: [Besu User Documentation](https://besu.hyperledger.org)  
**License**: Apache 2.0

## Repository Overview

Hyperledger Besu is an enterprise-grade, Java-based, Apache 2.0 licensed Ethereum client that is MainNet compatible.

**Key Information**:
- **GitHub**: https://github.com/hyperledger/besu
- **Documentation**: https://besu.hyperledger.org
- **Latest Release**: 25.12.0 (Dec 12, 2025)
- **Language**: Java 99.7%
- **License**: Apache 2.0
- **Status**: Active development (1.7k stars, 992 forks)

## Official Key Generation Methods

### Using Besu Operator CLI

According to the [official Besu documentation](https://besu.hyperledger.org), Besu provides operator commands for key management:

#### 1. Export Public Key from Private Key

```bash
besu public-key export --node-private-key-file=<path-to-nodekey>
```

#### 2. Export Address from Private Key

```bash
besu public-key export-address --node-private-key-file=<path-to-nodekey>
```

#### 3. Generate Block (for genesis block generation)

```bash
besu operator generate-blockchain-config
```

### Official File Structure

Based on Besu's standard configuration, the expected file structure includes:

#### Node Keys (P2P Communication)
- **Location**: `data/` directory (or `/data/besu/` in containers)
- **File**: `nodekey` - 64 hex characters (32 bytes) private key
- **Usage**: Used for P2P node identification and enode URL generation

#### Validator Keys (QBFT/IBFT Consensus)
- **Location**: Configured in `config.toml` via `miner-coinbase` or validator key path
- **File**: Typically `key.priv` or `key` (hex-encoded private key)
- **Usage**: Used for block signing in QBFT/IBFT consensus protocols

### Official Configuration Files

Besu uses TOML configuration files with standard locations:

```
/etc/besu/
├── genesis.json              # Network genesis block
├── config.toml               # Main Besu configuration
├── permissions-nodes.toml    # Node allowlist (optional)
└── permissions-accounts.toml # Account allowlist (optional)

/data/besu/
├── nodekey                   # P2P node private key (auto-generated if not provided)
└── database/                 # Blockchain database
```

## Key Generation Best Practices

### 1. Node Key (P2P) Generation

**Official Method**:
```bash
# Besu auto-generates nodekey on first startup if not provided
# Or generate manually using OpenSSL
openssl rand -hex 32 > nodekey
```

**Verification**:
```bash
# Check nodekey format (should be 64 hex characters)
cat nodekey | wc -c  # Should be 65 (64 chars + newline)
```

### 2. Validator Key Generation (QBFT)

**Method 1: Using OpenSSL (Standard)**
```bash
# Generate secp256k1 private key
openssl ecparam -name secp256k1 -genkey -noout -out key.priv

# Extract public key
openssl ec -in key.priv -pubout -outform PEM -out pubkey.pem

# Extract address using Besu
besu public-key export-address --node-private-key-file=key.priv > address.txt
```

**Method 2: Using quorum-genesis-tool (Recommended)**
```bash
npx quorum-genesis-tool \
  --consensus qbft \
  --chainID 138 \
  --validators 5 \
  --members 4 \
  --bootnodes 2
```

### 3. Key Format Compatibility

Besu supports multiple key formats:

- **Hex-encoded keys**: Standard 64-character hex string (0-9a-f)
- **PEM format**: Privacy Enhanced Mail format (base64 encoded)
- **Auto-detection**: Besu automatically detects format

## Official Documentation References

### Key Management
- **Operator Commands**: https://besu.hyperledger.org/Reference/CLI/CLI-Subcommands/#operator
- **Public Key Commands**: https://besu.hyperledger.org/Reference/CLI/CLI-Subcommands/#public-key
- **Key Management**: https://besu.hyperledger.org/HowTo/Configure/Keys

### Consensus Protocols
- **QBFT**: https://besu.hyperledger.org/HowTo/Configure/Consensus-Protocols/QBFT
- **IBFT 2.0**: https://besu.hyperledger.org/HowTo/Configure/Consensus-Protocols/IBFT
- **Clique**: https://besu.hyperledger.org/HowTo/Configure/Consensus-Protocols/Clique

### Configuration
- **Configuration File Reference**: https://besu.hyperledger.org/Reference/Config-Items
- **Genesis File**: https://besu.hyperledger.org/HowTo/Configure/Genesis-File
- **Permissions**: https://besu.hyperledger.org/HowTo/Use-Privacy/Permissioning

## Integration with Current Project

### Current Structure Compatibility

Our current structure is compatible with Besu's expectations:

```
keys/validators/validator-N/
├── key.priv      # ✅ Compatible (hex or PEM)
├── key.pem       # ✅ Compatible (PEM format)
├── pubkey.pem    # ✅ Compatible (PEM format)
└── address.txt   # ✅ Compatible (hex address)
```

**Note**: Besu can use any of these formats, so our current structure is valid.

### Recommended Updates

1. **Use Official Documentation Links**: Update all documentation to reference https://besu.hyperledger.org
2. **Key Generation**: Prefer methods documented in official Besu docs
3. **File Naming**: Current naming is acceptable, but can align with quorum-genesis-tool for consistency
4. **Validation**: Use Besu CLI commands for key validation

## Script Updates Required

### Update Key Generation Scripts

Replace any manual key generation with Besu-supported methods:

```bash
# OLD (may not be standard)
# Manual hex generation

# NEW (Besu-compatible)
# Use OpenSSL for secp256k1 keys
openssl ecparam -name secp256k1 -genkey -noout -out key.priv
besu public-key export-address --node-private-key-file=key.priv > address.txt
```

### Update Documentation Links

Replace generic references with official Besu documentation:
- ❌ "Besu documentation"
- ✅ "https://besu.hyperledger.org" or "Besu User Documentation (https://besu.hyperledger.org)"

## Verification Commands

### Verify Node Key
```bash
# Check nodekey exists and is correct format
test -f /data/besu/nodekey && \
  [ $(wc -c < /data/besu/nodekey) -eq 65 ] && \
  echo "✓ nodekey valid" || echo "✗ nodekey invalid"
```

### Verify Validator Key
```bash
# Verify private key exists
test -f key.priv && echo "✓ Private key exists" || echo "✗ Private key missing"

# Verify address can be extracted
besu public-key export-address --node-private-key-file=key.priv > /dev/null 2>&1 && \
  echo "✓ Validator key valid" || echo "✗ Validator key invalid"
```

## References

- **Official Repository**: https://github.com/hyperledger/besu
- **User Documentation**: https://besu.hyperledger.org
- **Wiki**: https://wiki.hyperledger.org/display/besu
- **Discord**: Besu channel for community support
- **Issues**: https://github.com/hyperledger/besu/issues