purple-explorer/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

eIquidus — a Node.js/Express blockchain block explorer for altcoins using the Bitcoin RPC protocol. It connects to a coin wallet via JSON-RPC, syncs blocks/transactions into MongoDB, and serves a web UI.

• Node.js ≥ 20.9.0, MongoDB ≥ 7.0.2
• Express v5, Pug templates, Mongoose ODM, Jasmine tests
• Configuration lives entirely in settings.json (created from settings.json.template)

Common Commands

# Run tests
npm test                   # jasmine test/*Spec.js

# Start the explorer
npm start                  # cluster mode (1 worker per CPU)
npm run start-instance     # single instance (dev/testing)
npm run start-pm2          # production via PM2

# Blockchain sync (run as separate processes, not part of the web server)
npm run sync-blocks        # sync new blocks from wallet
npm run sync-markets       # fetch exchange market data
npm run sync-peers         # discover network peers
npm run sync-masternodes   # update masternode list
npm run check-blocks       # verify block integrity

# Database maintenance
npm run reindex            # full reindex from wallet RPC
npm run create-backup      # backup MongoDB
npm run restore-backup     # restore MongoDB
npm run delete-database    # wipe all explorer data

# CSS compilation (SASS → CSS in public/css/)
node scripts/compile_css.js

Architecture

Request Flow

HTTP request
  → app.js (middleware: CORS, rate limiting, auth, TLS redirect)
  → routes/index.js (all web & API routes)
  → lib/database.js (Mongoose queries against models/)
  → lib/explorer.js (data transformation utilities)
  → views/*.pug (rendered response)

For live wallet data, routes call lib/nodeapi.js which wraps lib/jsonrpc.js for RPC calls.

Sync Flow

npm run sync-blocks
  → scripts/sync.js (orchestrator, uses worker threads)
  → lib/block_sync.js (parallel block fetching & processing)
  → lib/database.js (bulk writes to MongoDB)

Block sync is multi-threaded (configurable parallelism). It has elastic stack-size handling for overflow errors. The web server and sync scripts are separate processes — sync is triggered via cron, not by the web server.

Key Files

File	Purpose
app.js	Express setup: plugin loader, CORS, ACL builder, TLS redirect
lib/settings.js	Parses and validates settings.json; all config access goes through here
lib/database.js	All MongoDB queries; wraps Mongoose models
lib/explorer.js	Pure utility functions for formatting block/tx/address data
lib/block_sync.js	Multi-threaded block synchronization engine
lib/nodeapi.js	Wallet RPC wrapper
routes/index.js	All Express routes (web pages + REST API)
scripts/sync.js	Entry point for npm run sync-* commands
models/	12 Mongoose schemas: tx, address, addresstx, stats, richlist, masternode, peers, markets, orphans, heavy, networkhistory, claimaddress
lib/markets/	Per-exchange integrations (altmarkets, dextrade, dexomy, freiexchange, nonkyc, poloniex, xeggex, yobit)

Configuration

settings.json (gitignored, based on settings.json.template) controls everything: DB credentials, wallet RPC, port, TLS, themes, enabled pages, market exchanges, API access. Read through lib/settings.js to understand available options and their defaults.

Plugin System

Early-stage plugin system. Plugins are loaded in app.js from the plugins/ directory. Currently a placeholder only.

Testing

Tests are in test/ using Jasmine:

• explorerSpec.js — tests for lib/explorer.js utilities
• marketSpec.js — tests for market helper functions
• testData.js — shared fixtures

There is no linting configured. No TypeScript.