Explorer (node-backed) at explorer.zkcoins.com: public, privacy-preserving inscription/roots explorer

[TaprootFreak]

Goal

Offer a public zkCoins explorer at explorer.zkcoins.com, node-backed (it reads a node's public read API). Because zkCoins keeps all bookkeeping off-chain, this is a privacy explorer: it can only ever show public data (commitments, signatures, roots, sync state) and must never show balances, amounts, recipients, or transaction graphs — those are private and off-chain. That constraint is the product's unique angle: it proves activity without revealing it.

Conceptual basis: the protocol Information Model (zk-coins/docs PR #18) — only the 🟢 public class is explorer-visible.

Data source

Node-backed but node-agnostic: the explorer takes a configurable node base URL (default a public zkcoins.app node, e.g. https://api.zkcoins.app / https://dev-api.zkcoins.app). Anyone running their own node can point the explorer at it — same spirit as the wallet's switchable node.

Existing read endpoints (verified live on DEV)

• GET /api/info → {network, capabilities{address_list,username_claim,lnurl,multi_asset}, username_domain}
• GET /api/inscriptions/:txid → {commit_txid, reveal_txid, kind, status, commit_output_value, failure_reason, created_at, updated_at} (txid is the canonical, byte-reversed Bitcoin txid)
• GET /api/username/resolve/:username → {username, address} (service layer)
• GET /health, /health/ready, /health/publisher

Missing endpoints to add (this repo)

1. List inscriptions (feed) — GET /api/inscriptions?limit=&before= → paginated recent inscriptions (commit_txid, kind, status, block_height, observed_at). Today only single-by-txid exists.
2. Roots history — GET /api/roots?limit=&before= → MMR/SMT root chain (smt_root, prev_mmr_root, leaf_index, created_at).
3. Stats — extend /api/info or add GET /api/stats → total inscriptions, sync/tip height, inscriptions over time (bucketed), distinct public keys seen.
4. (optional) Commitment bytes — expose the on-chain commitment decode for a txid (public_key, signature, account_state_hash, output_coins_root) for a "decode the commitment" view.

All four are read-only and expose only public data. The owner-only endpoints (/api/balance, /api/history, /api/proof/:id) require keys and must not be used by the explorer.

MVP views (frontend)

1. Home / feed — live list of recent inscriptions (txid, kind, status, block, time) + headline stats + current global root.
2. Inscription detail — decode the 177-byte commitment (public key, Schnorr signature, message = account_state_hash ‖ output_coins_root), show commit/reveal txids, deep-link to a Bitcoin explorer (mempool / Mutinynet).
3. Roots / history — SMT + MMR root progression (append-only history, verifiable).
4. Search — by txid; plus handle resolve (name@…), clearly tagged as service-layer.

Guardrails

• Privacy: only public data. Never balances/amounts/recipients/account history. If a field could deanonymize, it does not belong here.
• txid byte order: display the canonical (reversed) Bitcoin txid; the node stores internal order. Get this right or cross-explorer links break.
• Protocol vs service: the explorer is protocol-facing (explorer.zkcoins.com). Service-specific bits (handles/LNURL) are clearly labeled as zkcoins.app conveniences, not protocol.

Proposed setup

• New repo zk-coins/explorer (static / Next.js), deployed to explorer.zkcoins.com via Cloudflare Pages — consistent with the other zk-coins web properties.
• Node URL configurable via env; ships pointing at a public node by default.

Acceptance criteria (MVP)

• Node exposes list-inscriptions, roots-history, and stats endpoints (read-only, public data only).
• explorer.zkcoins.com shows a live inscription feed, an inscription detail page, and a roots/history page.
• No private data is reachable through the explorer; owner-only endpoints are not called.
• txids render in canonical order and link correctly to a Bitcoin explorer.
• Node URL is configurable (operator-agnostic).