docs/architecture/ARCHITECTURE.md

# 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 an operator-focused 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)
Add Oracle Aggregator and CCIP Integration - Introduced Aggregator.sol for Chainlink-compatible oracle functionality, including round-based updates and access control. - Added OracleWithCCIP.sol to extend Aggregator with CCIP cross-chain messaging capabilities. - Created .gitmodules to include OpenZeppelin contracts as a submodule. - Developed a comprehensive deployment guide in NEXT_STEPS_COMPLETE_GUIDE.md for Phase 2 and smart contract deployment. - Implemented Vite configuration for the orchestration portal, supporting both Vue and React frameworks. - Added server-side logic for the Multi-Cloud Orchestration Portal, including API endpoints for environment management and monitoring. - Created scripts for resource import and usage validation across non-US regions. - Added tests for CCIP error handling and integration to ensure robust functionality. - Included various new files and directories for the orchestration portal and deployment scripts. 2025-12-12 14:57:48 -08:00			`# 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`

Archive legacy status docs and canonicalize genesis entrypoints 2026-04-13 21:45:16 -07:00			`The DeFi Oracle Meta Mainnet (ChainID 138) is an operator-focused 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.`
Add Oracle Aggregator and CCIP Integration - Introduced Aggregator.sol for Chainlink-compatible oracle functionality, including round-based updates and access control. - Added OracleWithCCIP.sol to extend Aggregator with CCIP cross-chain messaging capabilities. - Created .gitmodules to include OpenZeppelin contracts as a submodule. - Developed a comprehensive deployment guide in NEXT_STEPS_COMPLETE_GUIDE.md for Phase 2 and smart contract deployment. - Implemented Vite configuration for the orchestration portal, supporting both Vue and React frameworks. - Added server-side logic for the Multi-Cloud Orchestration Portal, including API endpoints for environment management and monitoring. - Created scripts for resource import and usage validation across non-US regions. - Added tests for CCIP error handling and integration to ensure robust functionality. - Included various new files and directories for the orchestration portal and deployment scripts. 2025-12-12 14:57:48 -08:00
			`## 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)`