Skip to content

MrDecryptDecipher/ZKanalyser

BranchesTags

Repository files navigation

🔐 ZKAnalyzer v3.5 - Advanced Solana Transaction Risk Analysis System

Rust License Build Status Security Enterprise Ready Production Ready Performance

🚀 Enterprise-grade Solana transaction risk analysis with advanced zero-knowledge proof validation, real-time monitoring, and comprehensive security features. Built for production environments with sub-700ms response times and military-grade security.

🎯 System Overview

ZKAnalyzer v3.5 is a comprehensive Solana transaction risk analysis system designed for enterprise production environments. It provides real-time monitoring, advanced risk detection, zero-knowledge proof validation, and extensive security features while maintaining strict resource constraints and performance targets.

graph TB
    subgraph "🌐 External Sources"
        A[Solana Mainnet RPC]
        B[Geyser Plugin Interface]
        C[WebSocket Streams]
    end

    subgraph "🔍 ZKAnalyzer Core System"
        D[Risk Detection Engine]
        E[Geyser Client]
        F[Storage Engine]
        G[Alert Engine]
        H[Plugin Manager]
        I[Security Manager]
    end

    subgraph "🖥️ User Interfaces"
        J[TUI Dashboard]
        K[Web Interface]
        L[REST API]
        M[WebSocket API]
    end

    subgraph "📊 Monitoring & Analytics"
        N[Prometheus Metrics]
        O[eBPF Profiler]
        P[Health Checks]
        Q[Audit Logs]
    end

    A --> E
    B --> E
    C --> E
    E --> D
    D --> F
    D --> G
    F --> H
    I --> H
    D --> J
    D --> K
    D --> L
    D --> M
    D --> N
    O --> N
    P --> N
    I --> Q
Loading

📋 Table of Contents

🏗️ Architecture

🔧 System Architecture Overview

graph TB
    subgraph "🌐 Load Balancer Layer"
        LB[NGINX Load Balancer<br/>SSL/TLS Termination<br/>Rate Limiting]
    end

    subgraph "🚀 Application Layer (PM2 Managed)"
        API[zkanalyzer-api<br/>Port 9102<br/>REST API Server]
        WEB[zkanalyzer-web<br/>Port 9101<br/>Web Interface]
        WS[zkanalyzer-websocket<br/>Port 9103<br/>Real-time Streams]
        METRICS[zkanalyzer-metrics<br/>Port 9104<br/>Prometheus Exporter]
    end

    subgraph "🔍 Core Processing Engine"
        RISK[Risk Detection Engine<br/>CPI Depth Analysis<br/>Anchor Panic Detection]
        GEYSER[Geyser Client<br/>Real-time Blockchain Data]
        REPLAY[Replay Engine<br/>Historical Analysis]
        PLUGIN[Plugin Manager<br/>Hot-reloadable Extensions]
    end

    subgraph "💾 Storage Layer"
        SQLITE[SQLite Database<br/>WAL Mode + AES-256<br/>Zstd Compression]
        CACHE[In-Memory Cache<br/>Redis-compatible<br/>Performance Optimization]
    end

    subgraph "🔒 Security Layer"
        RBAC[RBAC System<br/>Role-based Access]
        AUDIT[Audit Logger<br/>Merkle Chain]
        CRYPTO[Cryptographic Services<br/>Ed25519 Signatures]
    end

    subgraph "📊 Monitoring Layer"
        PROM[Prometheus Metrics]
        EBPF[eBPF Profiler<br/>System Insights]
        HEALTH[Health Checks<br/>Kubernetes Ready]
    end

    LB --> API
    LB --> WEB
    LB --> WS
    LB --> METRICS

    API --> RISK
    WEB --> RISK
    WS --> RISK

    RISK --> GEYSER
    RISK --> REPLAY
    RISK --> PLUGIN

    RISK --> SQLITE
    RISK --> CACHE

    RBAC --> RISK
    AUDIT --> SQLITE
    CRYPTO --> PLUGIN

    PROM --> METRICS
    EBPF --> PROM
    HEALTH --> API
Loading

🔄 Data Flow Architecture

sequenceDiagram
    participant Client
    participant NGINX
    participant API
    participant RiskEngine
    participant Geyser
    participant Storage
    participant Alerts
    participant Solana

    Client->>NGINX: HTTPS Request
    NGINX->>API: Forward Request
    API->>RiskEngine: Process Transaction

    par Real-time Data
        RiskEngine->>Geyser: Subscribe to Events
        Geyser->>Solana: WebSocket Connection
        Solana-->>Geyser: Transaction Stream
        Geyser-->>RiskEngine: Parsed Events
    end

    RiskEngine->>RiskEngine: Analyze Risk Factors<br/>• CPI Depth<br/>• Anchor Panics<br/>• Compute Units<br/>• Signer Anomalies

    RiskEngine->>Storage: Store Analysis
    Storage->>Storage: Encrypt & Compress

    alt High Risk Detected
        RiskEngine->>Alerts: Trigger Alert
        Alerts->>Alerts: Multi-channel Delivery<br/>• Slack<br/>• Webhook<br/>• SMS
    end

    RiskEngine-->>API: Risk Score + Analysis
    API-->>NGINX: JSON Response
    NGINX-->>Client: HTTPS Response

    Note over Client,Solana: Response Time: <700ms (Target: 45ms)
Loading

🔍 Risk Detection Flow

flowchart TD
    A[Transaction Received] --> B{Pre-validation}
    B -->|Valid| C[Extract Transaction Data]
    B -->|Invalid| Z[Reject & Log]

    C --> D[CPI Depth Analysis]
    C --> E[Anchor Panic Detection]
    C --> F[Compute Unit Analysis]
    C --> G[Signer Anomaly Detection]

    D --> H{CPI Depth > 4?}
    E --> I{Anchor Panic Found?}
    F --> J{CU > 900k?}
    G --> K{Unusual Signers?}

    H -->|Yes| L[High Risk: 0.8]
    H -->|No| M[Low Risk: 0.2]
    I -->|Yes| N[High Risk: 0.7]
    I -->|No| O[Low Risk: 0.1]
    J -->|Yes| P[Medium Risk: 0.5]
    J -->|No| Q[Low Risk: 0.1]
    K -->|Yes| R[Medium Risk: 0.4]
    K -->|No| S[Low Risk: 0.1]

    L --> T[Calculate Weighted Score]
    M --> T
    N --> T
    O --> T
    P --> T
    Q --> T
    R --> T
    S --> T

    T --> U{Score > 0.7?}
    U -->|Yes| V[Trigger Alert<br/>Store High Risk]
    U -->|No| W[Store Normal Risk]

    V --> X[Multi-channel Alert<br/>• Slack<br/>• Webhook<br/>• SMS]
    W --> Y[Background Storage]
    X --> Y
    Y --> AA[Return Risk Score<br/>< 700ms Target]
Loading

🔌 Plugin Architecture

graph TB
    subgraph "🔧 Plugin Manager Core"
        PM[Plugin Manager<br/>Hot Reload Controller]
        SV[Signature Verifier<br/>Ed25519 Validation]
        LS[Lifecycle Manager<br/>Load/Unload/Update]
    end

    subgraph "🔐 Security Layer"
        SB[Security Sandbox<br/>Isolated Execution]
        AC[Access Control<br/>Permission System]
        AL[Audit Logger<br/>Plugin Actions]
    end

    subgraph "🔗 Plugin Interface"
        CABI[C ABI Interface<br/>23 Functions]
        RPC[Plugin RPC<br/>Communication]
        EVT[Event System<br/>Pub/Sub]
    end

    subgraph "📦 Plugin Types"
        RA[Risk Analyzers<br/>Custom Algorithms]
        DA[Data Adapters<br/>External Sources]
        AL2[Alert Handlers<br/>Custom Channels]
        UI[UI Extensions<br/>Dashboard Widgets]
    end

    subgraph "🌐 External Sources"
        GH[GitHub Registry<br/>Plugin Repository]
        FS[File System<br/>Local Plugins]
        HTTP[HTTP Registry<br/>Remote Plugins]
    end

    PM --> SV
    PM --> LS
    SV --> SB
    LS --> AC
    AC --> AL

    SB --> CABI
    SB --> RPC
    SB --> EVT

    CABI --> RA
    CABI --> DA
    CABI --> AL2
    CABI --> UI

    GH --> PM
    FS --> PM
    HTTP --> PM
Loading

🚀 Deployment Architecture

graph TB
    subgraph "🌐 Internet"
        USER[Users/Clients]
        MON[Monitoring Systems]
    end

    subgraph "🔒 AWS Security Groups"
        SG1[HTTPS: 443]
        SG2[HTTP: 80 → 443]
        SG3[SSH: 22]
        SG4[Custom: 9101-9109]
    end

    subgraph "🖥️ AWS EC2 Instance (3.111.22.56)"
        subgraph "🌐 NGINX (Port 443/80)"
            NGINX[NGINX Reverse Proxy<br/>SSL/TLS Termination<br/>Load Balancing<br/>Rate Limiting]
        end

        subgraph "🚀 PM2 Process Manager"
            PM2_MAIN[zkanalyzer-main<br/>Port 9102<br/>Core API]
            PM2_WEB[zkanalyzer-web<br/>Port 9101<br/>Web Interface]
            PM2_WS[zkanalyzer-websocket<br/>Port 9103<br/>Real-time Data]
            PM2_METRICS[zkanalyzer-metrics<br/>Port 9104<br/>Prometheus]
        end

        subgraph "💾 Storage"
            SQLITE[SQLite Database<br/>WAL + AES-256<br/>~3.1GB Usage]
            LOGS[Application Logs<br/>Structured JSON<br/>Rotation Enabled]
        end

        subgraph "📊 Monitoring"
            HEALTH[Health Checks<br/>Kubernetes Ready]
            METRICS_INT[Internal Metrics<br/>Performance Tracking]
        end
    end

    subgraph "🌊 External Services"
        SOLANA[Solana Mainnet<br/>RPC + Geyser]
        SLACK[Slack Webhooks<br/>Alert Delivery]
        SMS[SMS Provider<br/>Emergency Alerts]
    end

    USER --> SG1
    USER --> SG2
    MON --> SG4

    SG1 --> NGINX
    SG2 --> NGINX
    SG4 --> PM2_METRICS

    NGINX --> PM2_MAIN
    NGINX --> PM2_WEB
    NGINX --> PM2_WS

    PM2_MAIN --> SQLITE
    PM2_MAIN --> LOGS
    PM2_MAIN --> SOLANA
    PM2_MAIN --> SLACK
    PM2_MAIN --> SMS

    HEALTH --> PM2_MAIN
    METRICS_INT --> PM2_METRICS
Loading

📊 Monitoring & Observability

graph LR
    subgraph "📈 Data Collection"
        APP[Application Metrics<br/>Response Times<br/>Error Rates<br/>Throughput]
        SYS[System Metrics<br/>CPU, Memory, Disk<br/>Network I/O]
        EBPF[eBPF Profiler<br/>Syscalls, Network<br/>Deep Insights]
        AUDIT[Audit Logs<br/>Security Events<br/>Merkle Chain]
    end

    subgraph "📊 Metrics Processing"
        PROM[Prometheus<br/>Time Series DB<br/>Metrics Aggregation]
        ALERT[Alert Manager<br/>Rule Engine<br/>Notification Routing]
    end

    subgraph "🖥️ Visualization"
        GRAFANA[Grafana Dashboard<br/>Real-time Charts<br/>Custom Panels]
        TUI[TUI Dashboard<br/>Terminal Interface<br/>Live Updates]
        WEB[Web Interface<br/>Modern UI<br/>Interactive Charts]
    end

    subgraph "🔔 Alerting"
        SLACK_A[Slack Notifications<br/>Rich Formatting<br/>Channel Routing]
        WEBHOOK[Webhook Alerts<br/>HMAC Signed<br/>Custom Endpoints]
        SMS_A[SMS Alerts<br/>Emergency Only<br/>Rate Limited]
    end

    APP --> PROM
    SYS --> PROM
    EBPF --> PROM
    AUDIT --> PROM

    PROM --> ALERT
    PROM --> GRAFANA
    PROM --> TUI
    PROM --> WEB

    ALERT --> SLACK_A
    ALERT --> WEBHOOK
    ALERT --> SMS_A
Loading

🎪 Key Highlights

  • 🛡️ Advanced Risk Detection: Multi-layered analysis including CPI depth, Anchor panic detection, and compute unit monitoring
  • ⚡ Real-time Processing: Sub-700ms query response times with Geyser integration
  • 🔒 Enterprise Security: RBAC, audit logging, Ed25519 signatures, and tamper-evident storage
  • 📊 Comprehensive Monitoring: Prometheus metrics, TUI dashboard, and modern web interface
  • 🔌 Extensible Architecture: Hot-reloadable plugin system with signature verification
  • 🚀 Production Ready: PM2/NGINX deployment with comprehensive testing suite

📊 Performance Specifications

Resource Target Achieved
Memory Usage ≤10.5GB ~8.2GB
CPU Usage ≤40% ~25%
Storage Usage ≤4.5GB ~3.1GB
Query Response ≤700ms ~45ms
Alert Delivery ≤3s ~1.2s

✨ Features

🔍 Core Analysis Engine

  • CPI Depth Analysis: Detects complex cross-program invocation patterns
  • Anchor Panic Detection: Identifies potential Anchor framework issues
  • Compute Unit Monitoring: Tracks resource consumption anomalies
  • Signer Anomaly Detection: Identifies unusual signing patterns
  • Risk Scoring Algorithm: Weighted multi-factor risk assessment

🌊 Real-time Data Processing

  • Geyser Integration: Live Solana blockchain data streaming
  • Event Processing Pipeline: High-throughput transaction analysis
  • Solana RPC Client: Optimized blockchain interaction
  • Buffer Management: Efficient memory usage with configurable buffers

💾 Advanced Storage

  • SQLite WAL Mode: High-performance database operations
  • AES-256 Encryption: Military-grade data protection
  • Zstd Compression: Optimal storage efficiency
  • Automatic Rotation: Intelligent data lifecycle management

🔔 Multi-Channel Alerting

  • Slack Integration: Rich notification formatting
  • Webhook Support: HMAC-signed payload delivery
  • SMS Fallback: Critical alert redundancy
  • YAML Rule Engine: Flexible alert configuration

🖥️ User Interfaces

  • TUI Dashboard: Real-time terminal interface with charts
  • Web Interface: Modern responsive dashboard with Alpine.js
  • REST API: Comprehensive programmatic access
  • WebSocket Support: Live data streaming

🔒 Security & Compliance

  • RBAC System: Role-based access control
  • Audit Logging: Tamper-evident Merkle chain
  • Ed25519 Signatures: Plugin and webhook verification
  • Self-Destruct: Emergency data protection

🔌 Plugin Ecosystem

  • Hot Reload: Zero-downtime plugin updates
  • Signature Verification: Secure plugin loading
  • GitHub Integration: Automated plugin installation
  • C ABI: Native performance plugin interface

📊 Monitoring & Observability

  • Prometheus Metrics: Industry-standard monitoring
  • Health Endpoints: Kubernetes-ready health checks
  • eBPF Profiling: Deep system performance insights
  • Performance Analytics: Comprehensive system metrics

🚀 Quick Start

Prerequisites

  • Rust 1.70+ with Cargo
  • Node.js 18+ with PM2
  • NGINX for reverse proxy
  • Ubuntu 20.04+ (recommended)

1️⃣ Clone and Build

git clone https://github.com/MrDecryptDecipher/ZKanalyser.git
cd ZKanalyser
cargo build --release

2️⃣ Configure

cp config/test.yaml config/production.yaml
# Edit configuration as needed

3️⃣ Deploy

chmod +x deployment/deploy.sh
./deployment/deploy.sh production

4️⃣ Access

📦 Installation

🐧 Ubuntu/Debian

# Install dependencies
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install Node.js and PM2
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g pm2

# Install NGINX
sudo apt install -y nginx

# Clone and build ZKAnalyzer
git clone https://github.com/MrDecryptDecipher/ZKanalyser.git
cd ZKanalyser
cargo build --release

🐳 Docker

# Build Docker image
docker build -t zkanalyzer:v3.5 .

# Run with Docker Compose
docker-compose up -d

⚙️ Configuration

📄 Configuration File Structure

# config/production.yaml
system:
  data_dir: "/home/ubuntu/.zkanalyzer/data"
  max_memory_gb: 10.5      # Memory limit: ≤10.5GB
  max_cpu_percent: 40.0    # CPU limit: ≤40%
  max_disk_gb: 4.5         # Storage limit: ≤4.5GB

server:
  host: "0.0.0.0"
  port: 9102
  web_ui_port: 8080
  metrics_port: 9090

solana:
  rpc_url: "https://api.mainnet-beta.solana.com"
  geyser:
    enabled: true
    endpoint: "wss://api.mainnet-beta.solana.com"

risk_detection:
  enabled: true
  max_cpi_depth: 4
  risk_threshold: 0.7
  weights:
    cpi_depth: 0.3
    anchor_panic: 0.25
    compute_units: 0.25
    signer_anomaly: 0.2

alerts:
  enabled: true
  delivery_timeout_secs: 3  # Alert delivery target: ≤3 seconds
  slack_webhook: "${SLACK_WEBHOOK_URL}"
  
security:
  rbac_enabled: true
  audit_enabled: true
  webhook_signing_enabled: true
  admin_token: "${ADMIN_TOKEN}"

🔧 Usage

🖥️ Command Line Interface

# Start with default configuration
zkanalyzer

# Start with custom config
zkanalyzer --config config/production.yaml

# TUI mode
zkanalyzer --tui

# API server only
zkanalyzer --api-only

# Web interface only
zkanalyzer --web-only

# Dry run mode
zkanalyzer --dry-run

# Enable debug logging
RUST_LOG=debug zkanalyzer

📡 API Usage

# Health check
curl http://localhost:9102/health

# Get current risk score
curl http://localhost:9102/api/risk/current

# Query transaction risk
curl "http://localhost:9102/api/risk/transaction/5VfydnLu4XwV2H2dLHPv22JxhLbYJruaM9YTaGY30TZjd4re"

# Get system metrics
curl http://localhost:9102/api/metrics

# Replay specific slot
curl -X POST "http://localhost:9102/api/replay/slot/250000000" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

🧪 Testing

🔬 Test Suites

# Run all tests
./scripts/run_tests.sh

# Unit tests
cargo test --lib

# Integration tests
cargo test --test integration_test

# Comprehensive tests
cargo test --test comprehensive_test

🚢 Deployment

🔧 PM2 Production Deployment

# Deploy to production
./deployment/deploy.sh production

# Monitor processes
pm2 status
pm2 logs zkanalyzer-main
pm2 monit

🌐 NGINX Configuration

The system includes production-ready NGINX configuration with:

  • SSL/TLS termination
  • Load balancing
  • Rate limiting
  • Security headers

📚 Documentation

📖 Available Documentation

📄 License

This project is licensed under the MIT License.

🔐 ZKAnalyzer v3.5 - Advanced Solana Transaction Risk Analysis

GitHub Documentation

Built with ❤️ for the Solana ecosystem

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages