mazacoin-explorer/REQUIREMENTS.md

Mazacoin Blockchain Explorer - Requirements

Project Overview

Build a full-featured blockchain explorer for Mazacoin (similar to blockchain.com or blockchair.com).

Domain: maza.example.com Mazacoin Node: Running on Windows PC at <MAZACOIN_NODE_IP> (Tailscale), wallet at E:\coins\MAZA

Core Features

1. Block Explorer

• Search by block height or hash
• Display: height, hash, timestamp, size, transactions, miner address
• Previous/next block navigation
• Latest blocks feed (real-time)

2. Transaction Viewer

• Search by transaction ID
• Display: inputs, outputs, amounts, fees, confirmations
• Visual input/output flow
• Transaction status (confirmed/pending)

3. Address Lookup

• Search by Mazacoin address
• Balance display
• Transaction history (paginated)
• QR code generation for receiving
• Total received/sent

4. Network Statistics Dashboard

• Current block height
• Network hashrate
• Mining difficulty
• Average block time
• Total supply
• Active addresses (24h)
• Transactions per day
• Mempool size

5. Live Node Map 🌍

• Interactive world map (Leaflet.js)
• Geo-located active Mazacoin nodes
• Real-time updates via WebSocket
• Show: location, IP (optional), version, uptime
• Node count by country

6. Charts & Analytics

• Hashrate over time (7d, 30d, all time)
• Transactions per day
• Difficulty adjustment history
• Block time trends

7. Rich List

• Top addresses by balance
• Percentage of total supply
• Privacy-friendly (optional anonymization)

8. Mining Stats

• Latest mined blocks
• Mining pool distribution (if detectable)
• Average block rewards

Tech Stack

Backend

• Language: Node.js + Express
• Database: MongoDB (for caching blockchain data)
• Blockchain: Mazacoin node RPC via maza-cli.exe
• Geolocation: ipapi.co or ip-api.com
• Real-time: WebSocket (Socket.io)

Frontend

• Framework: React (or vanilla JS if simpler)
• Maps: Leaflet.js
• Charts: Chart.js or Recharts
• Styling: TailwindCSS or similar
• Icons: Lucide or Font Awesome

Infrastructure

• Container: Docker + docker-compose
• Deployment: DashCaddy API (http://<PROXY_SERVER_IP>:3001)
• Reverse Proxy: Caddy (auto-configured via DashCaddy)
• Domain: maza.example.com

Mazacoin Node Connection

Node Location: Windows PC at <MAZACOIN_NODE_IP> (SSH: hello@<MAZACOIN_NODE_IP>, key at ~/.ssh/id_ed25519) Wallet Path: E:\coins\MAZA CLI: E:\coins\MAZA\daemon\maza-cli.exe

RPC Commands Available:

• getblockcount - Latest block height
• getblockhash <height> - Get block hash
• getblock <hash> - Get block details
• getrawtransaction <txid> 1 - Get transaction details
• getpeerinfo - Get connected nodes
• getnetworkinfo - Network stats
• getmininginfo - Mining difficulty, hashrate
• getdifficulty - Current difficulty

Connection Method:

1. Start Mazacoin node: E:\coins\MAZA\maza-qt.exe -server (enables RPC)
2. Or use daemon: Check if there's a mazacoind.exe in the daemon folder
3. Configure RPC credentials in maza.conf (create if needed)
4. Backend queries via SSH + maza-cli or direct RPC if port exposed

Project Structure

mazacoin-explorer/
├── backend/
│   ├── src/
│   │   ├── api/           # REST endpoints
│   │   ├── rpc/           # Mazacoin RPC client
│   │   ├── db/            # MongoDB models
│   │   ├── workers/       # Background sync workers
│   │   └── websocket/     # Real-time updates
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   ├── public/
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── pages/         # Block, TX, Address pages
│   │   ├── charts/        # Chart components
│   │   └── map/           # Node map
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
├── deploy.sh              # DashCaddy deployment script
└── README.md

Deployment Steps

1. Build Docker images
2. Push to registry or build on target
3. Deploy via DashCaddy API:

   curl -X POST http://<PROXY_SERVER_IP>:3001/api/docker/deploy \
     -H "Content-Type: application/json" \
     -d '{
       "name": "mazacoin-explorer",
       "domain": "maza.example.com",
       "port": 3000,
       "env": {...}
     }'
   

Design Requirements

• Theme: Dark mode by default (blockchain explorers are dark)
• Colors: Use Mazacoin brand colors if available, or crypto-blue palette
• Responsive: Mobile-friendly
• Performance: Fast search, lazy loading for large datasets
• UX: Clean, intuitive, minimal clicks to info

Security Considerations

• Rate limiting on API endpoints
• Input validation (block heights, addresses, tx IDs)
• No sensitive RPC credentials exposed
• Optional: Cloudflare proxy for DDoS protection

Testing

• Unit tests for RPC client
• Integration tests for API endpoints
• E2E tests for critical user flows (search, view block, etc.)

Timeline

Build this incrementally:

1. Phase 1: Backend RPC client + basic API (blocks, txs, addresses)
2. Phase 2: Frontend (search, block/tx viewer)
3. Phase 3: Network stats dashboard
4. Phase 4: Live node map
5. Phase 5: Charts + rich list

Success Criteria

• Can search and view any block, transaction, or address
• Live node map updates in real-time
• Network stats are accurate
• Fast load times (<2s for most pages)
• Deployed and accessible at maza.example.com

---

Note: User (Sami) has Mazacoin wallet but node is not currently running. You may need to coordinate with Krystie (me) to start the node or handle RPC connection setup.

When completely finished, run this command to notify me: openclaw system event --text "Done: Mazacoin explorer built and ready for deployment to maza.example.com" --mode now