smom-dbis-138/scripts/configure-network-decision-tree.md

Decision Logic Tree Documentation

Overview

The configuration tool uses a comprehensive decision logic tree to prevent erroneous configurations and guide users through valid configuration paths.

Decision Trees

1. Validator Count Decision Tree

Validator Count
├── 1 validator
│   └── ⚠ Warning: Centralized network, not suitable for production
│       └── User confirmation required
├── 2 validators
│   └── ⚠ Warning: Risk of consensus deadlock
│       └── User confirmation required
├── 3 validators
│   └── ⚠ Warning: Can tolerate 1 failure, recommend 4+
│       └── User confirmation required
├── Even number (4, 6, 8, ...)
│   └── ⚠ Warning: Can cause consensus issues
│       └── User confirmation required
└── Odd number (5, 7, 9, ...)
    └── ✅ Recommended for production

2. Network Architecture Decision Tree

Network Architecture
├── Sentries = 0
│   └── ⚠ Warning: Validators exposed directly
│       └── User confirmation required
├── Sentries < Validators
│   └── ⚠ Warning: May cause connectivity issues
│       └── Recommend: Sentries >= Validators
└── Sentries >= Validators
    └── ✅ Recommended configuration

3. RPC Configuration Decision Tree

RPC Configuration
├── RPC Nodes = 0
│   └── ⚠ Warning: No public RPC access
│       └── User confirmation required
├── RPC Enabled on Validators
│   └── ⚠ Security Risk: Validators exposed
│       └── User confirmation required (not recommended)
├── P2P Enabled on RPC Nodes
│   └── ⚠ Security Risk: RPC nodes exposed to network
│       └── User confirmation required (not recommended)
└── RPC Enabled on RPC Nodes, P2P Disabled
    └── ✅ Recommended configuration

4. Security Configuration Decision Tree

Security Configuration
├── CORS = '*'
│   └── ⚠ Security Risk: Allows all origins
│       └── User confirmation required (not recommended)
├── Host Allowlist = '0.0.0.0' or '*'
│   └── ⚠ Security Risk: Allows all hosts
│       └── User confirmation required (not recommended)
├── RPC Enabled without CORS or Host Restrictions
│   └── ⚠ Security Risk: Unrestricted access
│       └── Recommend: Add restrictions
└── CORS and Host Restrictions Configured
    └── ✅ Recommended configuration

5. Deployment Type Decision Tree

Deployment Type
├── VM Deployment
│   ├── Individual VMs
│   │   └── ✅ Full control, manual scaling
│   ├── VM Scale Sets
│   │   └── ✅ Auto-scaling, load balancing
│   └── Large Deployment (>50 nodes)
│       └── ⚠ Warning: Consider VM Scale Sets for cost optimization
├── AKS Deployment
│   └── ✅ Kubernetes orchestration, auto-scaling
└── Both AKS and VM
    └── ✅ Maximum flexibility, higher cost

6. Resource Allocation Decision Tree

Resource Allocation
├── JVM Memory > VM Size Capacity
│   └── ⚠ Warning: Memory exceeds VM capacity
│       └── Recommend: Increase VM size or reduce JVM memory
├── RPC VM Size < Validator VM Size
│   └── ⚠ Warning: RPC nodes need more resources
│       └── Recommend: RPC VM Size >= Validator VM Size
└── Resources Appropriate
    └── ✅ Recommended configuration

7. Dependencies Decision Tree

Dependencies
├── Blockscout Enabled, RPC Disabled
│   └── ✗ Error: Blockscout requires RPC
│       └── Fix: Enable RPC or disable Blockscout
├── Monitoring Enabled, No Components Selected
│   └── ⚠ Warning: Monitoring enabled but no components
│       └── Recommend: Enable monitoring components
├── Validator Count Mismatch
│   └── ⚠ Warning: Genesis validators != Node validators
│       └── Fix: Align validator counts
└── Dependencies Satisfied
    └── ✅ Recommended configuration

Validation Rules

Genesis Validation

1. Chain ID: Must be between 1 and 2147483647

   • Reserved chain IDs (1, 3, 4, 5, 42): Warning
   • Chain ID 138: ✅ Recommended

2. Block Period: Must be between 1 and 60 seconds

   • < 2 seconds: Warning (may cause instability)
   • 2+ seconds: ✅ Recommended

3. Epoch Length: Must be between 1000 and 1000000

   • < 10000: Warning (frequent validator set changes)
   • 10000+: ✅ Recommended

4. Request Timeout: Must be between 1 and 60 seconds

   • = Block Period: Warning (should be less)

   • < Block Period: ✅ Recommended

5. Gas Limit: Must be valid hex, between 5000 and max

   • Invalid format: Error
   • Too low/high: Error
   • Valid range: ✅ Recommended

6. Validators: At least 1 required

   • < 4: Warning (recommend 4+)
   • Even number: Warning (recommend odd)
   • Odd number, >= 4: ✅ Recommended

Network Validation

1. Cluster Name: Must be valid Kubernetes name

   • Invalid characters: Error
   • Too long (>63 chars): Error
   • Valid format: ✅ Recommended

2. Resource Group: Must be valid Azure name

   • Invalid characters: Error
   • Too long (>90 chars): Error
   • Valid format: ✅ Recommended

3. VNet Address Space: Must be valid CIDR

   • Invalid format: Error
   • Valid CIDR: ✅ Recommended

4. Subnets: Must be within VNet, valid CIDR

   • Not within VNet: Error
   • Invalid CIDR: Error
   • Valid configuration: ✅ Recommended

5. Node Counts: Must be >= 0

   • Validators = 0: Error
   • Sentries = 0: Warning
   • RPC = 0: Warning
   • All > 0: ✅ Recommended

Besu Configuration Validation

1. Ports: Must be unique, valid range (1-65535)

   • Port conflicts: Error
   • Privileged ports (<1024): Warning
   • Valid ports: ✅ Recommended

2. RPC Configuration:

   • Validators with RPC: Warning (security risk)
   • RPC nodes without RPC: Error
   • RPC nodes with P2P: Warning (security risk)
   • Valid configuration: ✅ Recommended

3. CORS Configuration:

   • Wildcard '*': Warning (security risk)
   • Missing protocol: Warning
   • Valid origins: ✅ Recommended

Deployment Validation

1. Deployment Type: Must be 'aks', 'vm', or 'both'

   • Invalid type: Error
   • Valid type: ✅ Recommended

2. VM Deployment:

   • SSH key not found: Error
   • Too many regions (>10): Warning
   • Valid configuration: ✅ Recommended

3. Large Deployments:

   • 50 nodes: Warning (consider VM Scale Sets)

   • 100 nodes: Warning (verify necessity)

   • Reasonable size: ✅ Recommended

Error Handling

Error Levels

1. Errors: Block configuration generation

   • Invalid values
   • Missing required fields
   • Configuration conflicts

2. Warnings: Allow configuration but warn user

   • Security risks
   • Performance issues
   • Best practice violations

3. Info: Informational messages

   • Decision tree applied
   • Configuration recommendations

Error Resolution

1. Automatic Fixes: Tool attempts to fix common issues

   • Missing SSH keys: Generate key
   • Validator count mismatch: Align counts
   • Port conflicts: Suggest alternative ports

2. User Confirmation: Tool asks user to confirm risky configurations

   • Security risks: User must confirm
   • Performance issues: User must confirm
   • Best practice violations: User must confirm

3. Manual Fixes: User must fix errors manually

   • Invalid values: User must correct
   • Configuration conflicts: User must resolve
   • Missing dependencies: User must provide

Usage Examples

Example 1: Single Validator (Error Prevention)

User: Number of validators: 1
Tool: ⚠ Warning: Single validator - network will be centralized
Tool: Continue with single validator? [y/N]: n
User: Number of validators: 4
Tool: ✅ Configuration accepted

Example 2: RPC Security (Decision Tree)

User: Enable CORS? [y/N]: y
User: CORS origins: *
Tool: ⚠ Warning: CORS wildcard allows all origins
Tool: Continue with wildcard CORS? [y/N]: n
User: CORS origins: https://yourdomain.com
Tool: ✅ Configuration accepted

Example 3: Deployment Type (Decision Tree)

User: Deployment type: vm
User: Number of nodes: 60
Tool: ⚠ Warning: Large VM deployment - consider VM Scale Sets
Tool: Switch to VM Scale Sets? [Y/n]: y
Tool: ✅ Configuration updated to use VM Scale Sets

Best Practices

1. Always Review Warnings: Warnings indicate potential issues
2. Confirm Security Risks: Never ignore security warnings
3. Validate Configuration: Run validation before deploying
4. Test Configuration: Test in dev environment first
5. Document Changes: Document any manual configuration changes

References

• Besu Configuration
• Kubernetes Best Practices
• Azure VM Sizes
• IBFT2 Consensus