Catalyst Block Explorer (new)

Modern replacement explorer + indexer for the Catalyst V2 node (Rust).

This repo is designed to be compatible with the current testnet RPC surface described in:

• catalyst-node-rust/docs/explorer-handoff.md
• catalyst-node-rust/crates/catalyst-rpc/src/lib.rs

Notes on Catalyst cycles

In Catalyst, a “block” corresponds to a consensus cycle. Cycles are time-based, and some cycles legitimately produce no block/LSU. In those cases, JSON-RPC calls like catalyst_getBlockByNumber(<cycle>) may return null, and the explorer will display “No block produced”.

Quick start

Prereqs

• Node.js 22+
• Catalyst testnet HTTPS JSON-RPC (TLS) via:
  • https://testnet-eu-rpc.catalystnet.org
  • https://testnet-us-rpc.catalystnet.org
  • https://testnet-asia-rpc.catalystnet.org

Install

npm ci

Configure

Copy env examples:

cp apps/indexer/.env.example apps/indexer/.env
cp apps/web/.env.example apps/web/.env

Edit apps/indexer/.env and set CATALYST_RPC_URL (default EU) or CATALYST_RPC_URLS for failover.

Common env vars (indexer):

• CATALYST_RPC_URL: single RPC base URL (HTTPS)
• CATALYST_RPC_URLS: comma-separated list for failover (EU,US,Asia recommended)
• RPC_TIMEOUT_MS: per-call timeout (default 5000)
• RPC_ENDPOINT_COOLDOWN_MS: cooldown before retrying a failed endpoint (default 30000)

Security / safety:

• The indexer performs a startup network identity check and will refuse to run unless the RPC reports the expected chain_id, network_id, and genesis_hash for catalyst-testnet.
• TLS verification must be enabled. The indexer refuses to start if NODE_TLS_REJECT_UNAUTHORIZED=0 is set.

If the testnet is reset (new genesis), update these env vars to match catalyst_getSyncInfo:

• CATALYST_EXPECTED_NETWORK_ID
• CATALYST_EXPECTED_CHAIN_ID (hex or decimal)
• CATALYST_EXPECTED_GENESIS_HASH

Run (indexer + web)

npm run dev

• Indexer/API: http://localhost:4040
• Web UI: typically http://localhost:5173 (Vite will pick another port if it’s taken)

Production deployment

See deploy/README.md for:

• systemd unit + env example for running the indexer as a service
• nginx site config example (static asset caching, API rate limiting, short API caching)
• update steps for syncing apps/web/dist/ to the nginx-served directory

What’s included (MVP)

• Latest blocks (consensus cycles), block detail, tx detail, address detail
• SQLite-backed indexing loop using catalyst_getBlocksByNumberRange + catalyst_getTransactionReceipt
• Rate-limit backoff support for RPC error code -32029