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:

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

```toml
# 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):
```toml
# Transaction Pool
# (No options = use layered pool defaults)
```

**Example** (tuned, with eviction to reduce stuck txs):
```toml
# 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](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**:
```toml
# 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**:
   ```bash
   # 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**:
   ```bash
   systemctl restart besu-validator
   # or
   systemctl restart besu-rpc-core
   ```

3. **Verify**:
   ```bash
   # 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):
   ```toml
   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:

```bash
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

```bash
# 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](https://besu.hyperledger.org/public-networks/concepts/transactions/pool)
- [Besu Configuration Reference](https://besu.hyperledger.org/public-networks/reference/cli/options)
- [Besu 23.10.0 Release Notes](https://github.com/hyperledger/besu/releases/tag/23.10.0)

---

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