Aeru Blockchain Explorer

A comprehensive, feature-rich blockchain explorer for the Aeru (ARU) network. Built with Next.js, TypeScript, and PostgreSQL, providing real-time blockchain data visualization, transaction tracking, and a built-in faucet system.

Features

Block, transaction, and address explorer
Real-time network statistics and dashboard
Universal search (blocks, transactions, addresses)
Public REST API with rate limiting
Faucet system with Discord OAuth
MetaMask network integration
WebSocket support for live updates

Quick Start

Prerequisites

Node.js 20.x or higher
PostgreSQL 12+
npm or yarn
Access to Aeru RPC endpoint

Installation

Clone the repository

git clone https://github.com/soosho/aeru-explorer.git
cd aeru-explorer

Install dependencies
```
npm install
```
Set up environment variables
```
cp .env.example .env
```
Edit .env with your configuration (see Configuration section).

Set up the database

# Connect to PostgreSQL and run the schema
psql -U your_user -d your_database -f src/lib/schema.sql

# Or using the connection string from .env
psql $DATABASE_URL -f src/lib/schema.sql

Run database migrations (if using faucet)
```
npm run migrate-faucets
```

Start development server

# Development mode (Next.js only)
npm run dev

# Development mode with sync service
npm run dev:all

Open your browser
```
http://localhost:3000
```

Configuration

Create a .env file in the root directory with the following variables:

Required Variables

# Aeru RPC Endpoints
NEXT_PUBLIC_RPC_URL=https://rpc.aruscan.com
NEXT_PUBLIC_WSS_URL=wss://wss.aruscan.com
NEXT_PUBLIC_URL=https://yourdomain.com

# PostgreSQL Database
POSTGRES_HOST=127.0.0.1
POSTGRES_USER=explorer
POSTGRES_DATABASE=explorer
POSTGRES_PASSWORD=your_database_password
POSTGRES_PORT=5432

# Network Information
NEXT_PUBLIC_NETWORK_NAME=Aeru
NEXT_PUBLIC_NETWORK_SYMBOL=ARU
SERVER_IP=your_server_ip

Optional Variables (for Faucet)

# Discord OAuth (Required for faucet)
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_REDIRECT_URI=https://yourdomain.com/api/discord/callback
DISCORD_GUILD_ID=your_discord_guild_id

# Discord Bot (Optional)
DISCORD_BOT_TOKEN=your_discord_bot_token

# Faucet Configuration
FAUCET_PRIVATE_KEY=your_faucet_private_key
FAUCET_AMOUNT=0.2
FAUCET_MIN_BALANCE=1.0

Security Note: Never commit your .env file or expose private keys. The FAUCET_PRIVATE_KEY should be kept secret and never shared.

Database Setup

Initial Setup

Create PostgreSQL database

CREATE DATABASE explorer;
CREATE USER explorer WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE explorer TO explorer;

Run schema

psql -U explorer -d explorer -f src/lib/schema.sql

Initialize sync status (optional)

INSERT INTO sync_status (last_synced_block) VALUES (0);

Database Schema

The explorer uses the following main tables:

blocks - Block data
transactions - Transaction data
addresses - Address balances and statistics
sync_status - Blockchain sync status
faucets - Faucet claim tracking (if using faucet)

All tables are indexed for optimal query performance.

Deployment

Production Build

Build the application
```
npm run build
```

Start production server

# Next.js only
npm start

# With sync service
npm run start:all

Deployment Options

Option 1: Traditional VPS/Server

Set up Node.js and PostgreSQL on your server

# Ubuntu/Debian example
sudo apt update
sudo apt install nodejs npm postgresql

Clone and build

git clone https://github.com/soosho/aeru-explorer.git
cd aeru-explorer
npm install
npm run build

Set up environment variables

cp .env.example .env
nano .env  # Edit with your values

Set up database (see Database Setup section)

Run with PM2 (recommended)

npm install -g pm2

# Start Next.js
pm2 start npm --name "aeru-explorer" -- start

# Start sync service
pm2 start npm --name "aeru-sync" -- run sync-service

# Save PM2 configuration
pm2 save
pm2 startup

Set up reverse proxy (Nginx example)

server {
    listen 80;
    server_name yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Set up SSL (Let's Encrypt)

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

Option 2: Docker Deployment

Create a Dockerfile:

FROM node:20-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Production image
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

EXPOSE 3000
ENV PORT 3000

CMD ["node", "server.js"]

Build and run:

docker build -t aeru-explorer .
docker run -p 3000:3000 --env-file .env aeru-explorer

Sync Service

The sync service continuously indexes the blockchain. It should run as a background process:

# Using PM2
pm2 start npm --name "aeru-sync" -- run sync-service

# Or as a systemd service
sudo nano /etc/systemd/system/aeru-sync.service

[Unit]
Description=Aeru Explorer Sync Service
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/aeru-explorer
Environment="NODE_ENV=production"
ExecStart=/usr/bin/npm run sync-service
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable aeru-sync
sudo systemctl start aeru-sync

Usage

Development

# Start development server
npm run dev

# Start with sync service
npm run dev:all

# Run linting
npm run lint

Available Scripts

npm run dev - Start Next.js development server
npm run dev:all - Start Next.js + sync service
npm run build - Build for production
npm start - Start production server
npm run start:all - Start production + sync service
npm run sync-service - Run blockchain sync service
npm run migrate-faucets - Run faucet database migration
npm run backfill-addresses - Backfill address data
npm run resync-balances - Resync address balances

API Endpoints

The explorer provides a public API. See /api page for full documentation.

Key endpoints:

GET /api/stats - Network statistics
GET /api/v1/block/{number} - Block information
GET /api/v1/tx/{hash} - Transaction information
GET /api/v1/address/{address} - Address information
GET /api/miners - Top miners
GET /api/holders - Top holders

Rate Limiting: 5 requests per second per IP (with progressive cooldowns)

Troubleshooting

Database Connection Issues

Verify PostgreSQL is running: sudo systemctl status postgresql
Check connection credentials in .env
Ensure database exists and user has proper permissions

Sync Service Not Working

Check RPC endpoint is accessible
Verify database connection
Check sync service logs: pm2 logs aeru-sync

Build Errors

Clear .next folder: rm -rf .next
Reinstall dependencies: rm -rf node_modules && npm install
Check Node.js version: node --version (should be 20+)

Faucet Issues

Verify Discord OAuth credentials
Check faucet wallet has sufficient balance
Verify private key is correct format (no 0x prefix)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

This project is open source. Please check the repository for license details.

Acknowledgments

Built for the Aeru Network
Uses Next.js and Ethers.js
Inspired by modern blockchain explorers

Support

Documentation: Check the /api page for API documentation
Issues: GitHub Issues
Discord: Aeru Discord
Telegram: Aeru Telegram

Donations

If you find this explorer useful, donations are appreciated. This address accepts any EVM-based coin:

0x25d835981bf2879526c5482951304eb13e4c661b

Made for the Aeru community

Name		Name	Last commit message	Last commit date
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Aeru Blockchain Explorer

Features

Quick Start

Prerequisites

Installation

Configuration

Required Variables

Optional Variables (for Faucet)

Database Setup

Initial Setup

Database Schema

Deployment

Production Build

Deployment Options

Option 1: Traditional VPS/Server

Option 2: Docker Deployment

Sync Service

Usage

Development

Available Scripts

API Endpoints

Troubleshooting

Database Connection Issues

Sync Service Not Working

Build Errors

Faucet Issues

Contributing

License

Acknowledgments

Support

Donations

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Aeru Blockchain Explorer

Features

Quick Start

Prerequisites

Installation

Configuration

Required Variables

Optional Variables (for Faucet)

Database Setup

Initial Setup

Database Schema

Deployment

Production Build

Deployment Options

Option 1: Traditional VPS/Server

Option 2: Docker Deployment

Sync Service

Usage

Development

Available Scripts

API Endpoints

Troubleshooting

Database Connection Issues

Sync Service Not Working

Build Errors

Faucet Issues

Contributing

License

Acknowledgments

Support

Donations

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages