yedad_eye 0.1.0

# 👁️ YEDAD EYE - Matrix Engine & Network Explorer

<p align="center">
  <a href="#en-doc">English</a> •
  <a href="#fa-doc">فارسی</a>
</p>

---

<div id="en-doc" lang="en" dir="ltr">

## 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

```text
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:

```toml
[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:

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

```

### 🚀 Usage Example

```rust
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](https://github.com/adelsobhani/yedad_eye/blob/main/LICENSE) file for details.

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

---

<div id="fa-doc" lang="fa" dir="ltr">
  
## مستندات فارسی

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

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

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

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

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

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

```text
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 نودهای دیگر دریافت می‌کنند:

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

```

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

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

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

```

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

```rust
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](https://github.com/adelsobhani/yedad_eye/blob/main/LICENSE) را مطالعه کنید.

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