# 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:

```bash
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

```bash
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