proxmox/docs/06-besu/RPC_REVIEW_FOR_BESU_DEPLOYMENT.md

# Full RPC Review for Hyperledger Besu Permissioned Blockchain

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

---

**Date**: 2025-01-20  
**Purpose**: Comprehensive review of RPC configuration for Foundry deployment to Besu  
**Issues**: Connection timeout and "Known transaction" errors

---

## Executive Summary

### Issues Identified
1. **Connection Timeout**: RPC connection issues causing deployment failures
2. **"Known Transaction" Error**: Transactions already in pool, not being cleared

### Root Causes
- RPC endpoint connectivity issues
- Transaction pool not clearing duplicate transactions
- Possible transaction pool size limits
- Network timeout settings too aggressive

---

## 1. RPC Endpoint Configuration

### Current Configuration
- **RPC URL**: `http://192.168.11.211:8545`
- **Network**: Internal (192.168.11.0/24)
- **Protocol**: HTTP JSON-RPC

### Configuration File
- **File**: `smom-dbis-138/config/config-rpc-core.toml`
- **Type**: Core/Admin RPC node configuration

### RPC APIs Enabled
```toml
rpc-http-api=["ETH","NET","WEB3","TXPOOL","QBFT","ADMIN","DEBUG","TRACE"]
```

**Status**: ✅ All required APIs enabled

---

## 2. Besu RPC Node Configuration

### Key Settings

#### Network Settings
- **P2P Port**: 30303
- **RPC HTTP Port**: 8545
- **RPC HTTP Host**: 0.0.0.0 (all interfaces)
- **RPC HTTP Timeout**: Not explicitly set (default 60s)

#### Transaction Pool
- **TXPOOL API**: ✅ Enabled
- **Transaction Pool Size**: Not explicitly configured
- **Transaction Pool Configuration**: Default Besu settings

#### Permissions
- **Account Permissioning**: Disabled (`permissions-accounts-config-file-enabled=false`)
- **Node Permissioning**: Enabled (`permissions-nodes-config-file-enabled=true`)

---

## 3. Transaction Pool Analysis

### "Known Transaction" Error

#### Cause
- Transaction already exists in validator transaction pools
- Transaction not being cleared after failures
- Transaction pool not synchronized between nodes

#### Besu Behavior
- Besu tracks transactions by hash
- Duplicate transaction submissions are rejected
- Transaction pool maintains transactions until included or expired

#### Solutions
1. **Clear transaction pool**: Restart Besu nodes
2. **Use different nonce**: Skip to next available nonce
3. **Increase gas price**: Replace existing transaction
4. **Check transaction status**: Verify if transaction was actually sent

---

## 4. Network Connectivity Issues

### Connection Timeout

#### Possible Causes
1. **Network latency**: High latency to RPC node
2. **Firewall rules**: Blocking connections
3. **RPC timeout**: Besu RPC timeout too short
4. **Node overload**: RPC node under heavy load
5. **Connection pool**: Too many concurrent connections

#### Diagnosis
- Test ping connectivity to RPC host
- Test port connectivity (8545)
- Measure RPC response times
- Check for network packet loss

---

## 5. Besu Permissioned Network Considerations

### Permission Requirements
1. **Account Permissioning**: Disabled ✅
2. **Node Permissioning**: Enabled (validators must be allowlisted)
3. **RPC Access**: Internal network only

### Transaction Submission
- Transactions must be properly signed
- Gas price must meet minimum requirements
- Transaction must be from allowed account (if account permissioning enabled)

---

## 6. Transaction Pool Configuration

### Besu Default Limits
- **Transaction Pool Size**: 4096 transactions (default)
- **Pending Transaction Limit**: 4096 per account (default)
- **Transaction TTL**: 60 seconds (default)

### Configuration Options
```toml
# Transaction pool settings (if needed)
tx-pool-max-size=4096
tx-pool-limit-by-account-percentage=1.0
tx-pool-hash-limit=1024
```

### Current Status
- ⚠️ Transaction pool settings not explicitly configured
- Using Besu defaults

---

## 7. Recommendations

### Immediate Actions

#### 1. Fix Connection Timeout
```bash
# Increase RPC timeout in foundry.toml
[rpc_endpoints]
chain138 = "http://192.168.11.211:8545"

# Use longer timeout in scripts
cast send ... --rpc-url "$RPC_URL" --timeout 30000
```

#### 2. Clear Transaction Pool
```bash
# Option 1: Restart Besu RPC node
sudo systemctl restart besu-rpc-core

# Option 2: Clear transaction pool via admin API
cast rpc admin_removePeer --rpc-url "$RPC_URL" <peerId>
```

#### 3. Check Transaction Status
```bash
# Check if transaction exists
cast rpc eth_getTransactionByHash --rpc-url "$RPC_URL" <txHash>

# Check transaction pool content
cast rpc txpool_content --rpc-url "$RPC_URL"
```

#### 4. Use Higher Gas Price for Replacements
```bash
# Increase gas price to replace existing transaction
cast send ... --gas-price 3000000000  # 3 gwei
```

### Configuration Changes

#### 1. Increase RPC Timeout
```toml
# config-rpc-core.toml
rpc-http-timeout=120  # Increase from default 60s
```

#### 2. Configure Transaction Pool
```toml
# config-rpc-core.toml
# Transaction pool limits
tx-pool-max-size=8192
tx-pool-limit-by-account-percentage=0.5
```

#### 3. Enable Transaction Pool APIs
```toml
# Ensure TXPOOL API is enabled
rpc-http-api=["ETH","NET","WEB3","TXPOOL","ADMIN","DEBUG"]
```

### Best Practices

#### 1. Transaction Management
- Always check transaction status before retrying
- Use explicit nonces to avoid conflicts
- Implement retry logic with exponential backoff
- Clear transaction pool if errors persist

#### 2. Network Configuration
- Use stable network connections
- Monitor network latency
- Configure appropriate timeouts
- Use connection pooling

#### 3. Deployment Strategy
- Verify RPC connectivity before deployment
- Check transaction pool status
- Use appropriate gas prices
- Monitor transaction confirmations

---

## 8. Diagnostic Commands

### RPC Connectivity
```bash
# Test basic connectivity
cast chain-id --rpc-url http://192.168.11.211:8545

# Test RPC response time
time curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
  http://192.168.11.211:8545
```

### Transaction Pool Status
```bash
# Check transaction pool status
cast rpc txpool_status --rpc-url http://192.168.11.211:8545

# Check pending transactions
cast rpc txpool_content --rpc-url http://192.168.11.211:8545

# Check specific account transactions
cast rpc eth_getTransactionCount <address> pending \
  --rpc-url http://192.168.11.211:8545
```

### Transaction Verification
```bash
# Check if transaction exists
cast rpc eth_getTransactionByHash --rpc-url "$RPC_URL" <txHash>

# Check transaction receipt
cast rpc eth_getTransactionReceipt --rpc-url "$RPC_URL" <txHash>
```

---

## 9. Foundry Configuration

### Recommended foundry.toml Settings
```toml
[rpc_endpoints]
chain138 = "http://192.168.11.211:8545"

[rpc_endpoints.chain138]
timeout = 30000  # 30 seconds
```

### Deployment Script Best Practices
```bash
# Use explicit timeout
cast send ... --rpc-url "$RPC_URL" --timeout 30000

# Check transaction status before retrying
TX_HASH=$(cast send ... --rpc-url "$RPC_URL")
cast receipt "$TX_HASH" --rpc-url "$RPC_URL"
```

---

## 10. Action Items

### High Priority
1. ✅ Review RPC configuration (THIS DOCUMENT)
2. ⏳ Increase RPC timeout settings
3. ⏳ Implement transaction status checking
4. ⏳ Add retry logic with backoff

### Medium Priority
1. ⏳ Configure transaction pool limits
2. ⏳ Monitor network connectivity
3. ⏳ Implement connection pooling
4. ⏳ Add comprehensive error handling

### Low Priority
1. ⏳ Optimize transaction pool settings
2. ⏳ Implement transaction deduplication
3. ⏳ Add transaction pool monitoring
4. ⏳ Create deployment health checks

---

## 11. Conclusion

### Current Status
- ✅ RPC APIs properly configured
- ⚠️ Connection timeout issues present
- ⚠️ "Known transaction" errors occurring
- ⚠️ Transaction pool management needed

### Next Steps
1. Implement timeout fixes
2. Add transaction status checking
3. Improve error handling
4. Monitor transaction pool status

---

**This review identifies the root causes of deployment issues and provides actionable recommendations for fixing them.**