GraphSentinel

GraphSentinel: Comprehensive Project Documentation & Technical Specification
1. Project Overview & Objective
GraphSentinel is an enterprise-grade hybrid security and threat intelligence platform engineered to bridge the performance gap between high-throughput artificial intelligence and cryptographically secure decentralized registries. Traditional security solutions struggle with either computational scalability or immutable verifiability. GraphSentinel solves this by executing intense, multi-dimensional deep learning analytics off-chain while anchoring absolute trust metrics, reputation scores, and state decisions onto an immutable on-chain ledger hosted on Base Sepolia Layer 2.

2. Detailed System Architecture & Component Breakdown
[Threat Data / Ingestion] 
       │
       ▼
[Off-Chain AI Layer] ──► (CNN: Spatial Vectors) & (GNN: Multi-Hop Topologies) ──► [MongoDB Storage]
       │
       ▼
[Backend Execution Bridge] ──► [Node.js / Ethers.js / Admin Private Key]
       │
       ▼
[On-Chain Settlement Layer] ──► [Alchemy RPC] ──► [Base Sepolia L2 (Solidity Contracts)] ──► [BaseScan Explorer]
A. The Off-Chain AI & Data Layer (Python, PyTorch, MongoDB)
Threat Ingestion Pipeline: Ingests high-frequency raw security logs, telemetry feeds, and visual vector payloads from connected network nodes.

Convolutional Neural Network (CNN) Engine: Processes localized spatial threat parameters, visual logging artifacts, and structural matrix anomalies.

Graph Neural Network (GNN) Engine: Treats system entities, IP endpoints, and transaction wallets as interconnected graph nodes and edges. It analyzes multi-hop network paths to map sophisticated, distributed attack propagation and clustering patterns.

MongoDB Storage Core: Acts as a high-speed transactional database storing intermediate data models, raw logs, feature embeddings, and real-time computation states, preventing database overhead on the blockchain.

B. The Backend Execution Bridge (Node.js, Express, Ethers.js)
API Routing & Management: Handles incoming requests from client dashboards and interfaces directly with the MongoDB database to fetch processed metrics.

Transaction Packaging & Cryptographic Signing: Constructs state-change payloads and signs them using Ethers.js tied to an isolated administrative wallet (AGENT_PRIVATE_KEY). This guarantees that only authorized backend intelligence nodes can trigger state transitions.

C. The On-Chain Layer (Base Sepolia L2, Solidity, Hardhat, Alchemy)
Alchemy RPC Provider: Facilitates high-speed, reliable JSON-RPC communication between the backend bridge and the Base Sepolia network.

Solidity Smart Contracts (Reputation.sol & DefensePool.sol): Implements tamper-proof data structures that record permanent trust scores, actor reputation standings, and system defense logs.

BaseScan Explorer: Provides public, transparent auditability where all contract deployment events and trust-score updates can be verified using immutable transaction hashes.

3. End-to-End Execution Workflow
Ingestion & Preprocessing: Raw security telemetry data is captured and sent to the off-chain processing cluster.

Deep Learning Inference: The CNN engine evaluates spatial and visual attributes, while the GNN engine maps entity relationships to uncover hidden threat vectors. The aggregated risk assessment is saved locally to MongoDB.

Payload Construction: The Node.js application fetches the computed score, formulates a smart contract function call, and passes it to the Ethers.js signing module.

Administrative Authorization: The transaction is cryptographically signed using the isolated administrative private key, establishing absolute origin authenticity.

Broadcasting & Settlement: The signed transaction is routed through Alchemy to the Base Sepolia Layer 2 testnet.

Smart Contract Enforcement: The target Solidity contract (Reputation.sol) executes the state update, enforcing strict access controls (onlyOwner) to block unauthorized modifications.

Verification: A transaction receipt is generated, allowing operators and auditors to inspect the immutable execution record directly on BaseScan.

4. Security, Access Control, and Design Paradigms
Key Isolation & Secret Management: All private administrative credentials are restricted strictly to server-side environment configurations (.env), completely isolating sensitive keys from public repositories.

Role-Based Modifier Enforcement: State-changing smart contract functions are bound to explicit access modifiers (onlyOwner), preventing unauthorized external actors from artificially inflating or deflating system trust scores.

Decentralized Auditability: By offloading heavy computing to Python/MongoDB and anchoring final validation hashes on Base Sepolia, the system avoids high gas costs while retaining full transparency.