Besu Certified Professional cheat sheet

Besu is an Apache 2.0 licensed Java EVM client; runs on mainnet, testnets, and private networks; supports PoW (Ethash) and PoA (Clique, IBFT 2.0, QBFT).

Architecture components: Ethereum mainnet and private network support; Vert.x-based JSON-RPC; RocksDB storage; pluggable consensus; P2P layer (devp2p, discovery v5); metrics via Prometheus.

Deployment options: binary distribution (tar.gz), Docker image (hyperledger/besu), Homebrew, or build from source; minimum Java 11 (Java 17 recommended for recent versions).

CLI flags: --data-path sets data directory; --genesis-file loads genesis JSON; --network selects predefined network (mainnet, goerli, sepolia, dev); --rpc-http-enabled exposes JSON-RPC.

Data directory layout: DATABASE (RocksDB), caches, keystore, network key; backup by stopping node and copying data path; do not copy while running.

Besu requires genesis file for private networks; genesis defines chainId, difficulty, gasLimit, alloc (pre-funded accounts), and consensus config (e.g., ibft2, qbft, clique).

Ports: 30303 P2P TCP/UDP; 8545 JSON-RPC HTTP; 8546 WebSocket; 8551 Engine API (post-merge); 9545 metrics; 5050 GraphQL (if enabled).

Besu can run as archive or full node; --sync-mode=FULL or SNAP (default for mainnet); archive mode requires --sync-mode=FULL and --data-storage-format=BONSAI (or FOREST).

Besu supports multi-tenancy via --rpc-http-api=... and --rpc-http-apis; can enable/disable API methods per transport; use --rpc-http-cors-origins to restrict browser access.

Genesis file is JSON; mandatory fields: config (chainId, consensus), nonce, timestamp, gasLimit, difficulty, mixHash, coinbase, alloc, extraData.

chainId must be unique per network; used in transaction replay protection (EIP-155); Besu rejects mismatched chainId.

alloc section pre-funds accounts with wei balances; keys are addresses without 0x prefix; can also set code and storage for predeployed contracts.

Consensus config: for IBFT 2.0 use "ibft2": {blockperiodseconds, epochlength, requesttimeoutseconds}; for QBFT use "qbft": {blockperiodseconds, epochlength, requesttimeoutseconds}; for Clique use "clique": {period, epoch}.

extraData encodes initial validators: for IBFT/QBFT, RLP-encoded list of validator addresses with 0x prefix and 32-byte vanity prefix/suffix; for Clique, 32-byte vanity + signer addresses + 65-byte signature.

bootnodes: enode URLs (enode://pubkey@ip:port) for initial peer discovery; can also use --bootnodes flag; static-nodes.json for persistent peers.

permissions config: nodes whitelist (nodes-allowlist), accounts allowlist; configured via permissions configuration file (permissions_config.toml) and --permissions-nodes-config-file-enabled.

Genesis file must be identical across all nodes; any mismatch causes fork or connection failure; validate with --genesis-file and check logs for genesis hash.

To change consensus or validators, update genesis and restart network, or use QBFT/IBFT validator vote via JSON-RPC (qbft_proposeValidatorVote).

PoW (Ethash) used on Ethereum mainnet pre-merge; Besu supports it but not recommended for private networks due to energy and speed; difficulty adjusts per block.

Clique (PoA) uses signed blocks by authorized signers; period defines block time; epoch defines voting period; signers vote in/out via clique_propose; vulnerable to censorship but simple.

IBFT 2.0 is BFT PoA; requires 2f+1 validators to commit where f is faulty nodes; block finality immediate; validator set changes via voting; blockperiodseconds sets minimum block time.

QBFT is improved IBFT 2.0; requires 2f+1 validators; supports dynamic validator sets, higher throughput, and is recommended for new private networks; uses qbft_ JSON-RPC methods.

Validator set size: IBFT 2.0 and QBFT require at least 4 validators for fault tolerance (f=1); with 3 validators f=0, one failure halts network; recommended 4+.

Validator voting: qbft_proposeValidatorVote or ibft_proposeValidatorVote adds/removes validator; proposal requires majority (more than half) of validators; takes effect after epoch.

Block time: blockperiodseconds is minimum; if block not full, empty blocks are produced; set to 0 for on-demand blocks (only when transactions exist) in QBFT/IBFT 2.0.

Finality: IBFT/QBFT blocks are final once committed; no forks; PoW and Clique can reorganize; Clique finality is probabilistic.

Start Besu: besu --data-path=/path --genesis-file=/path/genesis.json --bootnodes=enode://... --p2p-port=30303 --rpc-http-enabled.

Check sync status: eth_syncing returns false when synced; admin_peers lists connected peers; net_peerCount returns number of peers.

Log levels: --logging=INFO|DEBUG|TRACE|ERROR; logs to console or file; use --log-file for persistent logs; increase to DEBUG for troubleshooting.

Metrics: enable with --metrics-enabled --metrics-port=9545 --metrics-host=0.0.0.0; expose Prometheus format; Grafana dashboards available; monitor block height, peer count, CPU, memory.

Common issues: no peers (check bootnodes, firewall, p2p port), genesis mismatch (compare genesis hash in logs), out of memory (increase -Xmx), slow sync (check disk I/O, use SSD).

Health checks: eth_blockNumber increasing; eth_syncing false; admin_nodeInfo returns enode and version; web3_clientVersion returns Besu version.

Backup and restore: stop node, copy data directory; restore by copying back; ensure same genesis and config; do not copy while running to avoid corruption.

Upgrade Besu: stop node, replace binaries, restart; data directory compatible across minor versions; check release notes for breaking changes; backup before upgrade.

Enable JSON-RPC: --rpc-http-enabled --rpc-http-host=0.0.0.0 --rpc-http-port=8545 --rpc-http-api=ETH,NET,WEB3,ADMIN,QBFT.

Namespaces: ETH (eth_*), NET (net_*), WEB3 (web3_*), ADMIN (admin_*), DEBUG (debug_*), TRACE (trace_*), MINER (miner_*), QBFT (qbft_*), IBFT (ibft_*), PERM (perm_*), PLUGINS.

eth_call executes read-only contract call without transaction; eth_sendRawTransaction submits signed transaction; eth_getTransactionReceipt returns status (0x1 success, 0x0 fail).

Gas estimation: eth_estimateGas returns gas needed; eth_gasPrice returns current gas price; EIP-1559 transactions use maxFeePerGas and maxPriorityFeePerGas.

Event logs: eth_getLogs filters by fromBlock, toBlock, address, topics; topics[0] is event signature hash; use for off-chain indexing.

WebSocket subscriptions: eth_subscribe with newHeads, logs, newPendingTransactions; requires --rpc-ws-enabled and --rpc-ws-api.

Error handling: JSON-RPC error codes (e.g., -32602 invalid params, -32000 execution reverted); check error.message for revert reason.

eth_chainId returns chain ID; net_version returns network ID; web3_clientVersion returns client name and version; eth_accounts returns node-managed accounts (if unlocked).

Besu privacy (private transactions) uses Tessera as privacy manager; configure --privacy-enabled --privacy-url=http://tessera:9081 --privacy-public-key-file=.

Private transaction flow: private payload encrypted and sent to Tessera; only parties with access see payload; on-chain only hash and sender visible.

Privacy groups: created via priv_newFilter or Tessera API; members identified by Tessera public keys; group membership defines who can decrypt.

Permissioning: local permissioning via configuration files (nodes allowlist, accounts allowlist) or on-chain permissioning via smart contracts (permissioning provider).

Local permissioning: nodes-allowlist file lists enode URLs; accounts-allowlist lists addresses; enable with --permissions-nodes-config-file-enabled and --permissions-accounts-config-file-enabled.

On-chain permissioning: deploy permissioning contracts (NodePermissioning, AccountPermissioning) and configure --permissions-nodes-contract-address and --permissions-accounts-contract-address.

Account permissioning restricts which accounts can send transactions; node permissioning restricts which nodes can connect; both can be enabled simultaneously.

Permissioning updates: local files require node restart or reload via perm_reloadPermissionsFromFile; on-chain updates take effect after transaction mined.

Use Solidity or Vyper; compile with solc; Besu supports EVM with London, Shanghai, Cancun forks depending on version and genesis config.

Deploy contract: send transaction with bytecode as data, no to address; contract address = keccak256(rlp(sender, nonce))[12:]; get via eth_getTransactionReceipt contractAddress.

Gas: contract deployment costs gas; set gasLimit in transaction; use eth_estimateGas; ensure account has sufficient balance.

Interact: eth_call for read-only functions; eth_sendRawTransaction for state-changing functions; encode function calls with ABI (e.g., web3.js, ethers.js).

Events: emit events in contract; retrieve via eth_getLogs; topics[0] = keccak256(event signature); indexed parameters become topics.

Testing: use Besu dev mode (--network=dev) for quick local chain; or private network with IBFT 2.0/QBFT; tools: Hardhat, Truffle, Remix connected via JSON-RPC.

Contract verification: not native to Besu; use third-party tools; source code verification not required for execution.

Upgradable contracts: use proxy patterns (e.g., Transparent Proxy, UUPS); Besu supports DELEGATECALL and CREATE2 for deterministic addresses.

Node key: private key for P2P identity; stored in data directory (e.g., key file); back up securely; enode derived from public key.

Account keys: Besu can manage accounts in keystore (--key-store-path); or use external signer (e.g., EthSigner) for secure key storage; never expose private keys in config files.

TLS for JSON-RPC: enable with --rpc-http-tls-enabled --rpc-http-tls-keystore-file --rpc-http-tls-keystore-password-file; supports mutual TLS (client auth) with --rpc-http-tls-client-auth-enabled.

TLS for P2P: not native; use network-level encryption (VPN, WireGuard) or TLS termination proxy for RPC.

Authentication: JSON-RPC has no built-in auth; use reverse proxy (nginx) with basic auth or JWT; Besu supports JWT for Engine API (--engine-jwt-secret).

Host binding: bind RPC to localhost (--rpc-http-host=127.0.0.1) unless remote access needed; restrict CORS (--rpc-http-cors-origins) and APIs (--rpc-http-api).

Firewall: restrict P2P port (30303) to known peers if permissioned; restrict RPC ports to trusted IPs; use security groups.

Key management best practices: use hardware security modules (HSM) or external signer for validator keys; rotate keys periodically; store keystore files encrypted.

Besu upgrades: stop node, backup data, replace binaries, restart; check release notes for database schema changes; major upgrades may require resync.

Migration from other clients (Geth, Nethermind): not directly compatible; must resync from genesis or use state export/import if supported; Besu can import Geth genesis.

Network upgrades (hard forks): update genesis config with fork block numbers (e.g., londonBlock, shanghaiTime); all nodes must upgrade before fork block.

Interoperability: Besu implements Ethereum JSON-RPC and P2P; can connect to other Ethereum clients (Geth, Nethermind, Erigon) on same network; supports EVM equivalence.

Cross-client private networks: ensure same genesis and consensus; Besu can peer with Geth (Clique) or other Besu nodes (IBFT/QBFT); not all clients support IBFT/QBFT.

Data migration: use eth_getLogs and eth_getBlockByNumber to export data; tools like blockchain-etl; no built-in export tool.

Backward compatibility: JSON-RPC API stable; deprecations announced in release notes; check --help for deprecated flags.

Docker upgrades: pull new image tag; ensure volume for data persists; update environment variables if needed; test in staging first.