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](https://besu.hyperledger.org/stable/Reference/CLI/CLI-Syntax/)
- [Kubernetes Best Practices](https://kubernetes.io/docs/concepts/security/)
- [Azure VM Sizes](https://docs.microsoft.com/azure/virtual-machines/sizes)
- [IBFT2 Consensus](https://besu.hyperledger.org/stable/HowTo/Configure/Consensus-Protocols/IBFT/)