Files

defiQUG dbd517b279 Sync workspace: config, docs, scripts, CI, operator rules, and submodule pointers.

- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains
- Omit embedded publish git dirs and empty placeholders from index

Made-with: Cursor

2026-04-12 06:12:20 -07:00

7.6 KiB

Raw Blame History

Besu Version-Specific Configuration Guide

Modern note: This guide still applies to the layered-transaction-pool era, but the fleet is now standardized on Besu 25.12.0, not 23.10.0. Read the compatibility guidance in that broader 23.10+ context.

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

Date: 2026-01-21
Version: Besu 23.10.0+ through 25.12.0
Status: ✅ ACTIVE

Overview

This guide documents configuration requirements specific to Besu version 23.10.0 and later, which introduced the layered transaction pool as the default implementation. The current fleet standard is Besu 25.12.0.

Version Information

Current Deployment

Besu Version: 25.12.0
Transaction Pool: Layered (default)
Consensus: QBFT
Network: Permissioned (ChainID 138)

Breaking Changes in 23.10.0

Layered Transaction Pool Default
- Layered pool is now the default (replaces legacy pool)
- Legacy pool options are incompatible and cause crashes
- Must use layered options or defaults
Deprecated Options
- tx-pool-max-size (legacy)
- tx-pool-limit-by-account-percentage (legacy)
- tx-pool-retention-hours (legacy)

Transaction Pool Configuration

❌ DO NOT USE (Legacy Options)

These options will crash Besu 23.10.0+ when using the default layered pool:

# DO NOT ADD - Causes "Could not use legacy transaction pool options with layered implementation"
tx-pool-max-size=8192
tx-pool-limit-by-account-percentage=0.5
tx-pool-retention-hours=12

Error Message:

Could not use legacy transaction pool options with layered implementation

✅ USE (Layered Options)

If you need to tune the transaction pool, use these layered options:

# Layered Transaction Pool Configuration (optional - defaults work well)
tx-pool-max-future-by-sender=200          # Max future transactions per sender
tx-pool-layer-max-capacity=12500000      # Max capacity per layer (bytes)
tx-pool-max-prioritized=2000             # Max transactions in prioritized layer
tx-pool-price-bump=10                    # Price bump for replacement (%)

Default Behavior

If no tx-pool options are specified, Besu 23.10.0+ uses:

Layered transaction pool (default)
Memory-based limits: ~25 MB total (12.5 MB per layer)
Prioritized layer: 2000 transactions max
Future transactions: 200 per sender max

Recommendation: Use defaults unless you have specific requirements.

Configuration by Node Type

Validator Nodes

File: /etc/besu/config-validator.toml

Required:

✅ No legacy tx-pool options
✅ Use layered pool (default) or layered options only

Example (minimal):

# Transaction Pool
# (No options = use layered pool defaults)

Example (tuned, with eviction to reduce stuck txs):

# Transaction Pool Configuration (Layered)
tx-pool-max-future-by-sender=200
tx-pool-layer-max-capacity=12500000
tx-pool-max-prioritized=2000
tx-pool-price-bump=10
# tx-pool-min-score=0 — omit; not supported in some Besu builds (see BLOCK_PRODUCTION_FIX_RUNBOOK.md)

To apply to all validators: bash scripts/fix-all-validators-and-txpool.sh (see TXPOOL_EVICTION_PREVENT_STUCK.md).

RPC Nodes

File: /etc/besu/config-rpc-core.toml (or similar)

Required:

✅ No legacy tx-pool options
✅ Use layered pool (default) or layered options only
✅ RPC timeout: 120+ seconds (for large deployments)

Example:

# Transaction Pool Configuration (Layered)
tx-pool-max-future-by-sender=200
tx-pool-layer-max-capacity=12500000
tx-pool-max-prioritized=2000
tx-pool-price-bump=10

# RPC Timeout (increased for large deployments)
rpc-http-timeout=120

Migration from Legacy Configuration

If You Have Legacy Options

Remove legacy options:

# Remove these lines from config files
tx-pool-max-size=8192
tx-pool-limit-by-account-percentage=0.5
tx-pool-retention-hours=12

Restart node:

systemctl restart besu-validator
# or
systemctl restart besu-rpc-core

Verify:

# Check logs for errors
journalctl -u besu-validator -n 50

# Verify service is active
systemctl is-active besu-validator

If You Need Tuning

Add layered options (if needed):

tx-pool-max-future-by-sender=200
tx-pool-max-prioritized=2000

Test and monitor:
- Monitor transaction inclusion rates
- Check for eviction issues
- Adjust if needed

Compatibility Checking

Automated Check

Use the compatibility checker script:

PROXMOX_USER=root bash scripts/check-besu-compatibility.sh

This script:

Checks for legacy tx-pool options
Verifies layered options (if present)
Reports compatibility issues

Manual Check

# Check for legacy options
grep -E 'tx-pool-max-size|tx-pool-limit-by-account-percentage' /etc/besu/config-validator.toml

# If found, remove them
# If not found, you're good (using defaults)

Troubleshooting

Validator Crashes on Startup

Symptom: Validator fails to start with error:

Could not use legacy transaction pool options with layered implementation

Solution:

Check config file for legacy options
Remove legacy options
Restart validator

Transactions Not Being Included

Possible Causes:

Transaction pool eviction (too many transactions)
Gas price too low
Network propagation issues
Validator not receiving transactions

Solutions:

Check transaction pool capacity (may need to increase tx-pool-layer-max-capacity)
Verify gas prices meet validator requirements
Check peer connections
Review validator logs for propagation issues

Empty Blocks