proxmox/docs/06-besu/BESU_VERSION_CONFIGURATION_GUIDE.md

Besu Version-Specific Configuration Guide

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

---

Date: 2026-01-21
Version: Besu 23.10.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.

---

Version Information

Current Deployment

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

Breaking Changes in 23.10.0

1. 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

2. 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

1. 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
   

2. Restart node:

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

3. Verify:

   # Check logs for errors
   journalctl -u besu-validator -n 50
   
   # Verify service is active
   systemctl is-active besu-validator
   

If You Need Tuning

1. Add layered options (if needed):

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

2. 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:

1. Check config file for legacy options
2. Remove legacy options
3. Restart validator

Transactions Not Being Included

Possible Causes:

1. Transaction pool eviction (too many transactions)
2. Gas price too low
3. Network propagation issues
4. Validator not receiving transactions

Solutions:

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

Empty Blocks

Possible Causes:

1. No transactions in pool
2. Transactions being evicted
3. Gas price rejection
4. Network connectivity issues

Solutions:

1. Check pending transactions
2. Verify transaction pool configuration
3. Check gas price settings
4. Verify peer connections

---

Best Practices

Configuration

1. Use Defaults First: Start with default layered pool settings
2. Tune Only If Needed: Only add layered options if you have specific requirements
3. Test Changes: Test configuration changes in non-production first
4. Monitor: Monitor transaction inclusion rates after changes

Monitoring

1. Block Production: Monitor block production rate
2. Transaction Inclusion: Track transaction inclusion rates
3. Pending Transactions: Monitor pending transaction counts
4. Pool Utilization: Monitor transaction pool utilization

Maintenance

1. Regular Checks: Run compatibility checks regularly
2. Version Updates: Review configuration when updating Besu
3. Documentation: Keep configuration documentation up to date
4. Backup: Backup config files before changes

---

References

• Besu Layered Transaction Pool Documentation
• Besu Configuration Reference
• Besu 23.10.0 Release Notes

---

Related Documents

• VALIDATOR_TXPOOL_MANUAL_UPDATE_GUIDE.md - Manual update procedures
• BLOCKCHAIN_STABILITY_REMEDIATION_PLAN.md - Comprehensive remediation plan
• NEXT_ACTIONS_EXECUTION_COMPLETE.md - Previous execution summary

---

Status: This guide is actively maintained. Update when Besu version changes or new requirements are identified.