# Architecture Documentation

**Last Updated**: 2025-01-27  
**Status**: Active

## Table of Contents

- [Overview](#overview)
- [Network Architecture](#network-architecture)
  - [Tiered Architecture](#tiered-architecture)
- [Consensus](#consensus)
- [Network Configuration](#network-configuration)
- [Infrastructure](#infrastructure)
  - [Azure Kubernetes Service (AKS)](#azure-kubernetes-service-aks)
  - [Networking](#networking)
- [Oracle System](#oracle-system)
  - [Oracle Aggregator](#oracle-aggregator)
  - [Oracle Publisher](#oracle-publisher)
  - [CCIP Integration](#ccip-integration)
- [DeFi Infrastructure](#defi-infrastructure)
  - [Standard Contracts](#standard-contracts)
- [Monitoring](#monitoring)
  - [Prometheus](#prometheus)
  - [Grafana](#grafana)
  - [Loki](#loki)
  - [Alertmanager](#alertmanager)
- [Security](#security)
  - [Key Management](#key-management)
  - [Network Security](#network-security)
  - [Permissioning](#permissioning)
- [Explorer](#explorer)
  - [Blockscout](#blockscout)
- [API Gateway](#api-gateway)
  - [Features](#features)
  - [Rate Limits](#rate-limits)
- [Data Management](#data-management)
  - [Node Types](#node-types)
  - [Backup](#backup)
- [Scalability](#scalability)
  - [Horizontal Scaling](#horizontal-scaling)
  - [Vertical Scaling](#vertical-scaling)
- [High Availability](#high-availability)
  - [Multi-AZ Deployment](#multi-az-deployment)
  - [Disaster Recovery](#disaster-recovery)
- [Performance](#performance)
  - [SLOs](#slos)
  - [Optimization](#optimization)
- [Future Enhancements](#future-enhancements)

## Overview

The DeFi Oracle Meta Mainnet (ChainID 138) is a production-ready blockchain network built on Hyperledger Besu with QBFT (Quorum Byzantine Fault Tolerance) consensus. The network is designed as a read network with public RPC endpoints and internal oracle publishers.

## Network Architecture

### Tiered Architecture

The network is organized into three tiers:

1. **Validators** (N≥4)
   - Private subnets, no public IPs
   - QBFT consensus participation
   - RPC disabled for security
   - Peered only to sentries

2. **Sentries** (N=3-5)
   - Public-facing P2P nodes
   - Peer to validators and other sentries
   - Limited RPC (internal only)
   - Port 30303 (TCP/UDP) for P2P

3. **RPC Nodes** (N=3-5)
   - Public HTTPS JSON-RPC
   - No P2P enabled
   - Read-only operations
   - Behind API gateway with rate limiting

## Consensus

- **Protocol**: QBFT (Quorum Byzantine Fault Tolerance)
- **Block Time**: ~2 seconds
- **Finality**: Immediate (BFT)
- **Validator Set**: 4+ validators
- **Epoch Length**: 30,000 blocks
- **Request Timeout**: 10 seconds

## Network Configuration

- **ChainID**: 138
- **Gas Limit**: ~30,000,000 per block
- **Network ID**: 138
- **Consensus**: QBFT

## Infrastructure

### Azure Kubernetes Service (AKS)

- **Cluster**: AKS with multiple node pools
- **Networking**: Azure CNI with VNet integration
- **Storage**: Azure Disks (Premium SSD) for chaindata
- **Secrets**: Azure Key Vault for key management
- **Monitoring**: Azure Monitor and Container Insights

### Networking

- **VNet**: Virtual Network with subnets for each tier
- **NSGs**: Network Security Groups with restrictive rules
- **Application Gateway**: HTTPS termination and load balancing
- **Private Endpoints**: Validator nodes in private subnets

## Oracle System

### Oracle Aggregator

- Chainlink-compatible oracle aggregator
- Round-based updates
- Access control (Admin and Transmitter roles)
- Heartbeat and deviation threshold policies

### Oracle Publisher

- Off-chain service fetching data from multiple sources
- Median aggregation
- Transaction signing via EthSigner
- Resilience logic (exponential backoff, reorg handling)

### CCIP Integration

- Chainlink CCIP for cross-chain oracle data
- CCIP sender and receiver contracts
- Cross-chain message validation

## DeFi Infrastructure

### Standard Contracts

- **WETH**: Wrapped Ether (WETH9 standard)
- **Multicall**: Batch contract calls
- **CREATE2 Factory**: Deterministic address deployment
- **Proxy**: Upgradeable oracle contracts

## Monitoring

### Prometheus

- Scrapes metrics from all Besu nodes
- Custom metrics for oracle updates
- Alert rules for node health and performance

### Grafana

- Dashboards for node health
- Block production metrics
- RPC performance metrics
- Oracle feed status

### Loki

- Log aggregation
- Structured logging
- Log retention policies

### Alertmanager

- Alert routing
- Notification channels
- Alert inhibition rules

## Security

### Key Management

- Azure Key Vault for validator keys
- EthSigner for oracle transaction signing
- HSM integration (optional)

### Network Security

- Private subnets for validators
- Network Security Groups
- TLS for internal communication
- WAF for RPC endpoints

### Permissioning

- Node permissioning (static-nodes.json)
- Account permissioning (optional)
- On-chain permissioning (optional)

## Explorer

### Blockscout

- Full-featured blockchain explorer
- Contract verification
- Token tracking
- Transaction history

## API Gateway

### Features

- Rate limiting (per method, per IP)
- Authentication (API keys, JWT)
- Method allowlists
- CORS configuration
- HTTPS termination

### Rate Limits

- Default: 1200 requests/minute
- eth_call: 600 requests/minute
- eth_getLogs: 300 requests/minute
- eth_getBlockByNumber: 600 requests/minute

## Data Management

### Node Types

- **Public RPC**: SNAP sync, 7-30 days retention
- **Internal Indexer**: ARCHIVE sync, persistent
- **Validators**: FULL sync, persistent

### Backup

- Daily volume snapshots
- Weekly cold backup
- Restore procedures documented

## Scalability

### Horizontal Scaling

- RPC nodes can scale based on load
- Sentry nodes can scale for P2P capacity
- Validators fixed (consensus requirement)

### Vertical Scaling

- Resource limits configured per tier
- Auto-scaling for RPC and sentry nodes
- Fixed resources for validators

## High Availability

### Multi-AZ Deployment

- Nodes distributed across availability zones
- Pod anti-affinity rules
- Pod disruption budgets

### Disaster Recovery

- Volume snapshots
- Cold backup procedures
- Restore runbooks

## Performance

### SLOs

- RPC availability: ≥99.9% monthly
- P95 RPC latency: ≤300ms
- Block lag: ≤2 blocks under normal conditions

### Optimization

- SNAP sync for RPC nodes
- Caching layer (Redis)
- CDN for static assets

## Future Enhancements

- On-chain permissioning
- Cross-chain bridges
- DeFi protocol integrations
- Layer 2 solutions
- Privacy features (Tessera)