👁️ YEDAD EYE - Matrix Engine & Network Explorer

English Documentation

yedad_eye is a dual-provider matrix aggregator, state synchronizer, and real-time network explorer tailored for the decentralized Yedad network ecosystem. It empowers network auditors, observers, and full nodes to fetch, validate, and dynamically align the complete 2D state matrix extracted from the interlinked horizontal and vertical Notepads (Space & Time separation).

📐 Matrix Architecture (Time × Space)

Within Yedad’s natural sharding design, blockchain history is decomposed into a strict mathematical coordinate system to eliminate traditional block propagation overhead:

Vertical Axis (Notepad 1): The global immutable network timeline (Pulses) advanced systematically by the elected Diamond Node.
Horizontal Axis (Notepad 2): Isolated local activity shards updated concurrently by individual nodes. Each cell holds an 8-byte cryptographic verification state (State CRC).

yedad_eye crawls these distributed shards, cross-references localized state histories against the central timeline, and maps out a transparent topology of the entire network.

📦 Directory Structure

yedad_eye/
├── .github/
│   └── workflows/
│       └── ci.yml               # Automated test suites and continuous integration (CI)
├── src/
│   ├── lib.rs                   # Main crate entrypoint and core provider traits
│   ├── types.rs                 # Data structures for Matrix rows and cell tracking
│   ├── error.rs                 # Native error handling for network & database layers
│   ├── providers/
│   │   ├── mod.rs               # Sub-module management for data fetchers
│   │   ├── network.rs           # HTTP client layer for light-weight remote observers
│   │   └── database.rs          # Read-only disk block scanner via native RocksDB
│   └── aggregator.rs            # Parallel execution engine for 2D matrix assembly
├── examples/
│   ├── observer_node.rs         # Ready-to-run demo for remote HTTP observers
│   └── full_node_eye.rs         # Ready-to-run demo for offline full-node disk scanning
├── Cargo.toml                   # Crate manifest, optional features, and dependencies
└── README.md                    # Comprehensive technical documentation

🛠️ Installation & Feature Flags

Add yedad_eye to your project's Cargo.toml manifest:

Mode A: Light-weight Network Observer (Default)

Ideal for web dashboards, monitoring bots, or client-side application wallets that pull metrics through a remote node’s Axum API:

[dependencies]
yedad_eye = { version = "0.1.0" }

Mode B: Full-Node Local Optimizer

Required for indexing nodes running alongside the main daemon, leveraging fast read-only iterators directly over physical database tracks:

[dependencies]
yedad_eye = { version = "0.1.0", features = ["rocksdb"] }

🚀 Usage Example

use std::sync::Arc;
use yedad_eye::{NetworkEyeProvider, aggregator::EyeAggregator};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = Arc::new(NetworkEyeProvider::new("[http://127.0.0.1:8080](http://127.0.0.1:8080)"));
    let aggregator = EyeAggregator::new(provider);

    match aggregator.reconstruct_matrix().await {
        Ok(matrix) => {
            println!("✅ Matrix compiled. Total active nodes tracked: {}", matrix.len());
        }
        Err(e) => eprintln!("❌ Matrix compilation halted: {}", e),
    }
    Ok(())
}

📜 License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

Maintained by Adel Sobhani (3adel.sob7ani@gmail.com).

مستندات فارسی

کتابخانه yedad_eye یک موتور تجمیع‌کننده ماتریسی، همگام‌ساز وضعیت و اکسپلورر زنده شبکه برای اکوسیستم غیرمتمرکز یداد (Yedad) است. این ابزار به حسابرسان شبکه، ناظران و فول‌نودها این امکان را می‌دهد تا ماتریس ۲ بعدی وضعیت کل شبکه را از طریق پیوند دادن داده‌های متقاطع فضا و زمان (تفکیک نوت‌پد ۱ و ۲) بازسازی و تحلیل کنند.

📐 معماری ماتریسی (زمان × فضا)

در ساختار شاردینگ طبیعی یداد، تاریخچه بلاکچین برای حذف سربار انتشار بلاک‌های سنتی، به یک سیستم مختصات ریاضی تبدیل شده است:

محور عمودی (نوت‌پد ۱): خط زمان محض و تغییرناپذیر شبکه (پالس‌ها) که به صورت سیستماتیک توسط نود الماسی جلو می‌رود.
محور افقی (نوت‌پد ۲): شاردهای فعالیت محلی که به صورت همزمان توسط هر نود آپدیت می‌شوند. هر سلول شامل یک هش تایید وضعیت ۴ بایتی (State CRC) است.

کتابخانه yedad_eye این شاردهای توزیع‌شده را جمع‌آوری کرده، با خط زمان مرکزی تطبیق می‌دهد و یک توپولوژی کاملاً شفاف از کل شبکه ترسیم می‌کند.

📦 ساختار درختی پروژه

yedad_eye/
├── .github/
│   └── workflows/
│       └── ci.yml               # خودکارسازی تست‌ها و بررسی کیفیت کدها (CI)
├── src/
│   ├── lib.rs                   # نقطه ورود اصلی کتابخانه و تعریف تریت‌های سراسری
│   ├── types.rs                 # استراکچرها و مدل‌های سلول و ردیف‌های ماتریس داده
│   ├── error.rs                 # مدیریت اختصاصی خطاهای لایه شبکه و دیتابیس
│   ├── providers/
│   │   ├── mod.rs               # مدیریت و یکپارچه‌سازی تأمین‌کنندگان داده
│   │   ├── network.rs           # لایه واکشی ناظران از طریق شبکه (HTTP/Axum)
│   │   └── database.rs          # لایه واکشی مستقیم محلی فول‌نودها (RocksDB)
│   └── aggregator.rs            # موتور چیدمان پازلی و بازسازی ماتریس ۲ بعدی
├── examples/
│   ├── observer_node.rs         # مثال کدهای راه‌اندازی برای کلاینت ناظر (Network Mode)
│   └── full_node_eye.rs         # مثال کدهای راه‌اندازی برای فول‌نودها (Direct DB Mode)
├── Cargo.toml                   # تنظیمات وابستگی‌ها، ویژگی‌های انتخابی (Features) و پکیج
└── README.md                    # راهنمای جامع مدیریت و مستندات پروژه

🛠️ نحوه نصب و ویژگی‌ها (Features)

کتابخانه yedad_eye را به فایل Cargo.toml پروژه خود اضافه کنید:

حالت اول: ناظر سبک تحت شبکه (حالت پیش‌فرض)

مناسب برای داشبوردهای وب، ربات‌های مانیتورینگ یا کیف‌پول‌هایی که اطلاعات را از طریق API نودهای دیگر دریافت می‌کنند:

[dependencies]
yedad_eye = { version = "0.1.0" }

حالت دوم: مخصوص فول‌نودها (Local Optimizer)

برای نودهایی که در کنار دیمون اصلی اجرا می‌شوند و نیاز دارند بدون واسطه شبکه، مستقیماً سکتورهای RocksDB را روی دیسک اسکن کنند:

[dependencies]
yedad_eye = { version = "0.1.0", features = ["rocksdb"] }

🚀 نمونه کد استفاده

use std::sync::Arc;
use yedad_eye::{NetworkEyeProvider, aggregator::EyeAggregator};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = Arc::new(NetworkEyeProvider::new("[http://127.0.0.1:8080](http://127.0.0.1:8080)"));
    let aggregator = EyeAggregator::new(provider);

    match aggregator.reconstruct_matrix().await {
        Ok(matrix) => {
            println!("✅ ماتریس شبکه با موفقیت چیده شد. تعداد نودهای فعال: {}", matrix.len());
        }
        Err(e) => eprintln!("❌ خطا در چیدمان ماتریس: {}", e),
    }
    Ok(())
}

📜 مجوز انتشار (License)

این پروژه تحت مجوز AGPL-3.0 منتشر شده است - برای جزییات بیشتر فایل LICENSE را مطالعه کنید.

توسعه و پشتیبانی توسط عادل سبحانی (3adel.sob7ani@gmail.com).

yedad_eye 0.1.0