peya-explorer/README.md

Peya Explorer

Modern explorer stack for Peya with:

• a fresh MySQL-first schema
• a dedicated RPC indexer
• a Fastify API
• a Next.js frontend

Old salstats code is reference material only. The production data model here is intentionally rebuilt from scratch around current Peya RPC behavior.

Apps

• apps/indexer - RPC ingestion and MySQL materialization
• apps/api - read API for the frontend and diagnostics tooling
• apps/web - public explorer UI
• packages/shared - shared types, labels, and formatting helpers

Data Model

The explorer is intentionally not a port of old salstats.

It stores:

• blocks
  • header data
  • reward and miner burn values
  • raw RPC JSON and blob
  • merge-mining marker derived from miner_tx.extra
• transactions
  • normalized tx type labels
  • burnt amount
  • source/destination asset types
  • return-address fields when present
• transaction_outputs
  • output amount
  • asset type
  • output target details
• protocol_events
  • protocol outputs per block
  • inferred stake_tx_hash
  • computed yield amount / percent when a stake match is found
• yield_metrics
  • get_yield_info materialized per block
  • slippage, locked tally, and network health

Indexer Notes

Primary RPC sources:

• get_block
• gettransactions
• get_yield_info
• /getheight

Current merge-mining detection:

• a block is marked merge-mined when miner_tx.extra contains a merge-mining tag
• this is suitable for current Peya diagnostics because aux-mined blocks are built with that tag

Current protocol/stake linkage:

• protocol outputs are stored raw first
• then the indexer tries to match a protocol unlock with the closest STAKE tx at block_height - 21601
• yield is computed as protocol unlock amount - original staked amount

That linkage is intentionally isolated in its own table logic so it can be tightened later if live RPC reveals a better authoritative signal.

Expected Server Layout

• Apache stays public on 80/443
• web runs on localhost
• api runs on localhost
• MySQL stores indexed chain data
• Redis is optional for caching and short-lived API responses

Environment

Each app reads env from its own process environment.

Common values:

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=peya
MYSQL_PASSWORD=secret
MYSQL_DATABASE=peya_explorer

PEYA_RPC_URL=http://127.0.0.1:17750
API_PORT=4100
NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:4100

Initial Commands

npm install
npm run db:migrate
npm run index:once
npm run dev:api
npm run dev:web

Current Status

Implemented and building:

• MySQL-first schema and migration
• dedicated RPC indexer
• Fastify read API
• Next.js frontend for dashboard, block list, and block detail

Still pending before production rollout:

• live validation against your localhost-exposed RPC
• tuning of stake/protocol linkage on real chain data
• search, charts, tx detail page polish, and Apache deployment snippets