Neurai Explorer

A blockchain explorer for the Neurai network, engineered for efficiency and scalability. It combines a Rust backend for high-throughput block synchronization with a Next.js frontend for the user interface.

Technical Overview

• Syncer Backend: Implemented in Rust using Tokio for asynchronous event processing. Handles block indexing with reduced memory overhead.
• Frontend Architecture: Built on Next.js 16 (App Router) and React 19, leveraging Server Components for optimized rendering.
• Analytics: Data visualization for network statistics, including difficulty and hashrate, utilizing Recharts.
• Asset Management: Native indexing and display of Neurai Assets (Tokens), including metadata and transfer ledgers.
• User Interface: Responsive layout constructed with Tailwind CSS, including system-aware theme support.
• Data Persistence: PostgreSQL database managed via SQLx for the syncer and Prisma for frontend queries.

---

Table of Contents

1. Architecture Overview
2. Tech Stack
3. Services
4. Getting Started
5. Configuration
6. Development
7. Project Structure
8. Contributing
9. License

---

Architecture Overview

The explorer follows a microservices architecture with four main components communicating through Docker's internal network.

---

Tech Stack

Core

Component	Technology	Version
Frontend Framework	Next.js (App Router)	16.x
UI Library	React	19.x
Language	TypeScript	5.x
Styling	Tailwind CSS	4.x
State Management	TanStack Query	Latest

Backend & Data

Component	Technology	Version
Syncer Runtime	Rust	2024 Edition
Async Runtime	Tokio	Latest
Database Driver	SQLx	Latest
Database	PostgreSQL	18.1
ORM (Frontend)	Prisma	Latest

Infrastructure

Component	Technology	Purpose
Containerization	Docker Compose	Service orchestration
Blockchain Node	Neurai Core	Network connectivity
Node Base	Debian 11	Node container OS

---

Services

Frontend (neurai-frontend)

Web interface for blockchain data visualization and interaction.

• Framework: Next.js 16 (App Directory structure)
• Features:
  • Block exploration with pagination support
  • Transaction inspection and search functionality
  • Network statistics dashboard
  • Asynchronous state management via React Query
• UI Components:
  • Icons provided by Lucide React & React Icons
  • Data visualization using Recharts
  • Conditional class utility via clsx

Syncer (neurai-syncer)

Rust-based service responsible for blockchain synchronization and indexing.

• Architecture: Asynchronous execution using the Tokio runtime
• Database: Direct PostgreSQL interaction via SQLx with compile-time query verification
• Performance:
  • Memory usage: ~500MB (efficient resource management)
  • Zero-copy deserialization implemented where applicable
  • Database connection pooling
• Communication: JSON-RPC interface to the Neurai Node

Database (neurai-postgres)

PostgreSQL instance for indexed blockchain data persistence.

• Engine: PostgreSQL 18.1 (Alpine Linux variant)
• Schema Management: Controlled via Prisma migrations
• Indexed Data:
  • Block data (height, hash, timestamp, transaction count)
  • Transaction records (txid, block reference, inputs/outputs)
  • Address ledgers and balance tracking

Node (neurai-node)

Neurai blockchain daemon instance.

• Source: NeuraiProject/Neurai v1.0.5
• Build: Custom Docker container based on Ubuntu 22.04
• Ports:
  • 19001: JSON-RPC interface exposure

---

Getting Started

Prerequisites

• Docker >= 24.0
• Docker Compose >= 2.20
• 8GB+ RAM recommended
• 50GB+ disk space for blockchain data

Quick Start

# Clone the repository
git clone https://github.com/your-org/neurai-explorer.git
cd neurai-explorer

# Build and start all services
docker compose up --build -d

# View logs
docker compose logs -f

Access Points

Service	URL	Description
Explorer UI	http://localhost:3000	Web interface
PostgreSQL	localhost:5432	Database (internal)
Node RPC	localhost:19001	Blockchain RPC

---

Configuration

Environment Variables

Syncer Configuration

# RPC Connection
RPC_HOST=node
RPC_PORT=19001
RPC_USER=neuraiuser
RPC_PASS=neuraipassword

# Database
DATABASE_URL=postgres://user:pass@postgres:5432/neurai

# Logging
RUST_LOG=info,sqlx=warn,reqwest=warn

Frontend Configuration

# Database (Prisma)
DATABASE_URL=postgres://user:pass@postgres:5432/neurai

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Node Configuration

The Neurai node is configured via neurai.conf:

server=1
rpcuser=neuraiuser
rpcpassword=neuraipassword
rpcallowip=0.0.0.0/0
rpcbind=0.0.0.0
txindex=1

Resource Limits

Default Docker resource configuration:

Service	Memory Limit	CPU Limit
Frontend	1GB	-
Syncer	2GB	-
PostgreSQL	2GB	-
Node	4GB	-

---

Development

Stopping Services

docker compose down

Rebuilding a Single Service

docker compose up --build -d <service-name>

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f neurai-syncer

Database Access

docker compose exec neurai-postgres psql -U neuraiuser -d neurai

---

Project Structure

neurai-explorer/
├── frontend/                 # Next.js application
│   ├── app/                  # App Router pages
│   ├── components/           # React components
│   ├── lib/                  # Utilities & helpers
│   └── prisma/               # Database schema
├── syncer/                   # Rust syncer service
│   ├── src/
│   │   ├── main.rs           # Entry point
│   │   ├── rpc/              # RPC client
│   │   └── db/               # Database operations
│   └── Cargo.toml
├── node/                     # Neurai node Dockerfile
├── docker-compose.yml        # Service orchestration
└── README.md

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.