d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
6333b88803218cab4e11b741aed1d1c7099c2c31
proxmox/docs/06-besu/BESU_OFFICIAL_REFERENCE.md
defiQUG fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details
docs: Ledger Live integration, contract deploy learnings, NEXT_STEPS updates 
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands
- CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround
- CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check
- NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere
- MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates
- LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 15:46:57 -08:00

6.7 KiB
Raw Blame History

Hyperledger Besu Official Repository Reference

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

Source: Hyperledger Besu GitHub Repository
Documentation: Besu User Documentation
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:

Official Key Generation Methods

Using Besu Operator CLI

According to the official Besu documentation, Besu provides operator commands for key management:

1. Export Public Key from Private Key

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

2. Export Address from Private Key

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

3. Generate Block (for genesis block generation)

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:

# Besu auto-generates nodekey on first startup if not provided
# Or generate manually using OpenSSL
openssl rand -hex 32 > nodekey

Verification:

# 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)

# 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)

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

Consensus Protocols

Configuration

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:

# 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:

Verification Commands

Verify Node Key

# 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

# 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

Reference in New Issue View Git Blame Copy Permalink