# Network Topology Specification

## Overview

This document specifies the network architecture for the ChainID 138 Explorer+ platform, including internal network structure, external access patterns, security boundaries, and CDN/WAF integration.

## Network Architecture

```mermaid
flowchart TB
    subgraph Internet[Internet]
        Users[End Users]
        Bots[Bots/Crawlers]
    end
    
    subgraph CDN[CDN Layer]
        Cloudflare[Cloudflare CDN/WAF]
    end
    
    subgraph Edge[Edge Layer]
        WAF[Web Application Firewall]
        LB[Load Balancer]
    end
    
    subgraph DMZ[DMZ Network<br/>192.168.11.0/24]
        API_GW[API Gateway]
        Web_Server[Web Server]
    end
    
    subgraph Internal[Internal Network<br/>10.0.0.0/16]
        Indexer[Indexer Service]
        Explorer_API[Explorer API]
        Mempool[Mempool Service]
        Search[Search Service]
    end
    
    subgraph Blockchain[Blockchain Network<br/>192.168.11.250:8545]
        Node1[ChainID 138 Node 1]
        Node2[ChainID 138 Node 2]
    end
    
    subgraph Data[Data Layer<br/>Private Network]
        DB[(PostgreSQL)]
        ES[(Elasticsearch)]
        Redis[(Redis Cache)]
    end
    
    Users --> Cloudflare
    Bots --> Cloudflare
    Cloudflare --> WAF
    WAF --> LB
    LB --> API_GW
    LB --> Web_Server
    
    API_GW --> Explorer_API
    Web_Server --> Explorer_API
    
    Explorer_API --> Indexer
    Explorer_API --> Mempool
    Explorer_API --> Search
    Explorer_API --> Redis
    
    Indexer --> Node1
    Indexer --> Node2
    Mempool --> Node1
    
    Explorer_API --> DB
    Indexer --> DB
    Search --> ES
```

## Network Segments

### External Network (Internet)

**Description**: Public internet access points for end users and bots.

**Access Patterns**:
- HTTPS requests to `https://explorer.d-bis.org`
- API requests to `https://api.explorer.d-bis.org`
- WebSocket connections for real-time updates

**Security Requirements**:
- All traffic must pass through CDN/WAF
- DDoS protection enabled
- Rate limiting at edge
- SSL/TLS termination

### CDN Layer (Cloudflare)

**Description**: Content delivery network and web application firewall.

**Configuration**:
- **CDN**: Static asset caching, global distribution
- **WAF**: DDoS protection, bot mitigation, rate limiting
- **SSL/TLS**: End-to-end encryption, certificate management
- **DNS**: DNS resolution and routing

**Rules**:
- Cache static assets (HTML, CSS, JS, images) for 1 hour
- Cache API responses for 1 minute (configurable)
- Block known malicious IPs
- Rate limit: 100 requests/minute per IP
- Challenge suspicious traffic (CAPTCHA, JavaScript challenge)

**Integration Points**:
- Origin: `192.168.11.140:443` (Blockscout/Web server)
- Tunnel: Cloudflare Zero Trust tunnel for internal services

### Edge Layer (DMZ - 192.168.11.0/24)

**Description**: Demilitarized zone containing publicly accessible services.

**Subnet**: `192.168.11.0/24`

**Components**:
- **API Gateway** (192.168.11.141)
  - Reverse proxy for API requests
  - Authentication/authorization
  - Rate limiting per API key
  - Request routing

- **Web Server** (192.168.11.140)
  - Serves frontend application
  - Static file hosting
  - Server-side rendering (if applicable)

**Security Rules**:
- No direct database access
- Communication with internal network via firewall rules only
- All outbound connections logged
- Intrusion detection system (IDS) monitoring

### Internal Network (10.0.0.0/16)

**Description**: Private network for backend services.

**Subnet**: `10.0.0.0/16`

**Service Allocation**:
- **10.0.1.0/24**: Explorer services (API, indexer, mempool)
- **10.0.2.0/24**: Search and analytics services
- **10.0.3.0/24**: Banking and compliance services
- **10.0.4.0/24**: VTM and conversational services

**Components**:
- Indexer Service (10.0.1.10)
- Explorer API (10.0.1.20)
- Mempool Service (10.0.1.30)
- Search Service (10.0.2.10)
- Analytics Service (10.0.2.20)

**Security Rules**:
- No internet access (outbound firewall)
- Communication with DMZ only via specific ports
- Internal service-to-service communication allowed
- All traffic encrypted (mTLS recommended)

### Blockchain Network (192.168.11.250:8545)

**Description**: Network segment containing blockchain nodes.

**Nodes**:
- **Primary Node**: `192.168.11.250:8545` (RPC)
- **Primary Node WS**: `192.168.11.250:8546` (WebSocket)
- **Backup Nodes**: Additional nodes for redundancy

**Access Rules**:
- Indexer service: Full access (archive, trace)
- Mempool service: Read access (pending tx), write access (submit tx)
- External services: Rate-limited public access via RPC endpoint
- Internal services: Direct access without rate limits

### Data Layer (Private Network)

**Description**: Network segment for data storage systems.

**Subnet**: `10.0.10.0/24` (isolated)

**Components**:
- **PostgreSQL** (10.0.10.10:5432)
  - Primary database
  - Read replicas for scaling
  
- **Elasticsearch** (10.0.10.20:9200)
  - Search index
  - Log aggregation
  
- **Redis** (10.0.10.30:6379)
  - Cache layer
  - Session storage
  - Rate limiting counters

- **TimescaleDB** (10.0.10.40:5432)
  - Time-series data
  - Mempool metrics

- **Neo4j** (10.0.10.50:7687)
  - Graph database
  - Cross-chain entity graph

**Security Rules**:
- No internet access
- Access only from internal services
- Network encryption (TLS)
- Database authentication required
- Backup network isolation

## External Access Patterns

### Public Web Access

**Flow**:
1. User → Cloudflare CDN (DNS resolution)
2. Cloudflare → WAF (security checks)
3. WAF → Load Balancer (traffic distribution)
4. Load Balancer → Web Server (content delivery)

**Ports**:
- HTTP: 80 (redirects to HTTPS)
- HTTPS: 443

### Public API Access

**Flow**:
1. Client → Cloudflare CDN
2. Cloudflare → WAF (rate limiting, bot detection)
3. WAF → API Gateway (authentication, routing)
4. API Gateway → Explorer API (request processing)

**Endpoints**:
- `https://api.explorer.d-bis.org/v1/*` (REST API)
- `https://api.explorer.d-bis.org/graphql` (GraphQL API)
- `wss://api.explorer.d-bis.org/ws` (WebSocket API)

### Internal Service Access

**Flow**:
- Direct communication within internal network
- Service discovery via DNS or service mesh
- Load balancing via service mesh or internal LB

## Security Boundaries

### Firewall Rules

**DMZ → Internal**:
- Allow: HTTP/HTTPS to API services (80, 443)
- Allow: Specific service ports (indexer, mempool)
- Deny: Database ports (5432, 9200, 6379)
- Deny: All other ports

**Internal → Data Layer**:
- Allow: Database connections from specific services
- Allow: Specific ports only (5432, 9200, 6379, 7687)
- Deny: All other access

**Internal → Blockchain Network**:
- Allow: RPC connections (8545, 8546)
- Deny: All other ports

**Internet → DMZ**:
- Allow: HTTP (80) → HTTPS redirect
- Allow: HTTPS (443) → Web/API servers
- Deny: All other ports

**Internal → Internet**:
- Deny: All outbound (except specific whitelisted services)
- Allow: Package updates (via proxy)
- Allow: External API calls (via gateway)

### Network Segmentation Benefits

1. **Isolation**: Compromise in one segment doesn't affect others
2. **Access Control**: Granular firewall rules
3. **Monitoring**: Network traffic analysis per segment
4. **Compliance**: Easier to demonstrate security controls

## CDN/WAF Integration

### Cloudflare Configuration

**DNS Records**:
- `explorer.d-bis.org` → Cloudflare proxy (orange cloud)
- `api.explorer.d-bis.org` → Cloudflare proxy
- Tunnel target: `192.168.11.140:80` (Web) or `192.168.11.141:443` (API)

**WAF Rules**:
1. **DDoS Protection**: Automatic mitigation
2. **Rate Limiting**:
   - 100 requests/minute per IP (general)
   - 10 requests/second per IP (API)
   - 1000 requests/minute per API key
3. **Bot Management**: Challenge suspicious bots
4. **Geographic Blocking**: Optional country restrictions
5. **IP Access Rules**: Whitelist/blacklist specific IPs

**Cache Rules**:
- Static assets: Cache for 1 hour
- HTML pages: Cache for 5 minutes
- API responses: No cache (dynamic data)
- GraphQL: No cache

### Cloudflare Tunnel (Zero Trust)

**Purpose**: Secure access to internal services without exposing ports.

**Configuration**:
- Tunnel endpoint: Internal load balancer
- Routes:
  - `explorer.d-bis.org/*` → `http://192.168.11.140:80`
  - `api.explorer.d-bis.org/*` → `http://192.168.11.141:443`

**Benefits**:
- No open ports to internet
- Encrypted connections
- Access control via Zero Trust policies
- Automatic failover

## Monitoring and Observability

### Network Monitoring

**Metrics to Track**:
- Bandwidth utilization per segment
- Connection counts
- Latency between segments
- Packet loss
- Firewall rule hit counts

**Tools**:
- Netflow/sFlow analysis
- Network packet capture (tcpdump, Wireshark)
- Network performance monitoring (PRTG, Zabbix)

### Security Monitoring

**Events to Monitor**:
- Firewall rule violations
- Unusual traffic patterns
- DDoS attack attempts
- Port scan attempts
- Failed authentication attempts

**Tools**:
- Intrusion Detection System (IDS)
- Security Information and Event Management (SIEM)
- Cloudflare security logs
- Firewall logs aggregation

## Implementation Guidelines

### Network Configuration

**IP Address Allocation**:
- Use CIDR notation for subnets
- Reserve IP ranges for future expansion
- Document all IP assignments

**DNS Configuration**:
- Internal DNS for service discovery
- External DNS via Cloudflare
- Service names: `service-name.internal.explorer`

**Load Balancing**:
- Use HAProxy or NGINX for internal LB
- Health checks for backend services
- Session affinity where needed

### Security Hardening

1. **Disable unused services**: Close unnecessary ports
2. **Use strong encryption**: TLS 1.2+ for all connections
3. **Implement network segmentation**: Isolate sensitive systems
4. **Regular security audits**: Review firewall rules
5. **Monitor network traffic**: Detect anomalies

## Migration from Current Setup

### Current Network Configuration

- **Blockscout Container**: `192.168.11.140:4000`
- **RPC Endpoint**: `192.168.11.250:8545`
- **Cloudflare Tunnel**: Configured for `explorer.d-bis.org`

### Migration Steps

1. Deploy new network segments
2. Configure firewall rules
3. Deploy services to appropriate segments
4. Update DNS and routing
5. Test connectivity
6. Monitor for issues
7. Gradually migrate traffic

## References

- Node & RPC Architecture: See `node-rpc-architecture.md`
- API Gateway: See `../api/api-gateway.md`
- Security Architecture: See `../security/security-architecture.md`
- Existing Blockscout setup: `../../docs/BLOCKSCOUT_COMPLETE_SUMMARY.md`

