morphit/docs/adr/0020-batch-k-explorer.md

# ADR-0020: Block explorer, trading-activity stats, APR display, cross-chain links

**Status:** Accepted
**Date:** 2026-04-29
**Deciders:** Agorise team (Claude collaborating)
**Supersedes:** —
**Related:**
- ADR-0008 (Phase 3b indexer architecture) — defines the
  feedback / orders schema this ADR's activity endpoint joins
  against.
- ADR-0011 (dynamic fee model) — touches the order schema's
  `external_tx_id` fields that we link out to mempool.space /
  xmrchain.net for completed BTC/XMR trades.
- ADR-0019 (release-trust-anchor) — same chain-direct,
  no-indexer-trust pattern this ADR's explorer reuses.

## Context

Through Batch J the project had a frontend, an indexer, and a
chat layer — but no surface for a curious passer-by to verify
"what's actually happening on this Morphit instance?" or for a
user to inspect the chain history of an order they were involved
in. The user asked for four related things:

1. A public **block explorer** at `/explorer` — search by
   `@username`, transaction id, or block number; polls real-time;
   lazy-loaded.
2. **Cross-chain links** — completed orders linking to
   appropriate external explorers for BTC/XMR; native Blurt
   linking to our own.
3. **Volume + market depth** — "make Morphit feel like a real
   exchange."
4. **APR display** near the user's BP balance.

The user was clear about polling-vs-websocket ("polling is
fine") and was open to design pushback on the depth-chart
question.

## Decision

### Middle-ground explorer

The explorer renders **Morphit-aware decoration** for the ~16
custom_json op ids Morphit uses (order, order_replace, feedback,
chat, operator_block, etc.) plus the three chain primitives
that show up in normal usage (transfer, comment, vote). Anything
else falls through to:

- Custom_json with unknown id → labeled "Other app" + raw-JSON
  fallback.
- Other native ops (witness votes, escrow, vesting) → labeled
  "Other chain op" + raw-JSON fallback.

This avoids the wide-coverage tail of building a generic Blurt
op renderer (every op type with proper field formatting would
take weeks). Users who hit the long tail get a working
raw-JSON view plus a "view on `blocks.blurtwallet.com`"
fallback link.

Routes:

- `/explorer` — search landing.
- `/explorer/account/[name]` — account view, polling 5s.
- `/explorer/block/[num]` — block detail, immutable so no poll.
- `/explorer/tx/[id]` — tx detail, immutable so no poll.
- `/explorer/activity` — volume + listings histogram, polling 30s.

All routes are **public**, no login required, lazy-loaded
(SvelteKit splits per-route by default; the chunks aren't
downloaded until the user navigates).

### Polling cadence

Per-page, fixed cadences:

| Page | Poll | Why |
|---|---|---|
| account | 5s | Real-time op stream feels live |
| activity | 30s | Coarse stats; faster wastes RPC traffic |
| block | none | Immutable once produced |
| tx | none | Immutable once produced |

All polls are **visibility-aware** (skip when `document.hidden`)
and cleaned up in `onDestroy`.

### Chain-direct fetch (NOT via indexer)

Same posture as ADR-0019: the explorer reads from chain RPC
directly via `BlurtClient`, NOT from the indexer's `/v1/...`
endpoints. The indexer caches Morphit-specific state
(orderbook, feedback) but doesn't index every chain op.
Going chain-direct also means the explorer keeps working when
the indexer is down or experiencing replay lag.

The activity page is the one exception — its volume aggregation
does need a SQL JOIN across feedback + orders (impossible from
a single RPC call). It hits the indexer for that data only.

### Cross-chain external explorer choices

| Asset | URL pattern | Rationale |
|---|---|---|
| BTC | `https://mempool.space/tx/{txid}` | Open-source, no JS tracking, fast. |
| XMR | `https://xmrchain.net/tx/{txid}` | Standard Monero community explorer. |
| BLURT (native) | `/explorer/tx/{trxid}` (own) | Self-hosted; falls back to `blocks.blurtwallet.com` if not found. |

XMR caveat surfaced in UI: Monero transactions are encrypted by
design. The external explorer can confirm a tx exists and was
included in a block, but the inputs/outputs are private. We don't
pretend otherwise in copy.

Per the user's correction: `blockchain.blurt.world` does NOT
exist. `blocks.blurtwallet.com` is the only Blurt fallback link
we surface.

### Real-exchange feel: volume + listings histogram (NOT depth chart)

The user asked "make Morphit feel similar to a real exchange."
The honest pushback is that Morphit isn't a matching engine —
each order has its own payment methods, region, and price model.
A traditional bid/ask depth chart would mislead users into
thinking they could just "hit the offer" when they can't.

What we DO show on `/explorer/activity`:

- **Trade count by asset** over 7d / 30d / 90d windows (exact).
- **Estimated volume** per asset, computed as the midpoint of
  each completed order's amount range (since the chain doesn't
  carry exact fill amounts on feedback ops). Clearly labeled
  "estimated" in the UI.
- **Listings histogram** — current buy vs sell count per asset,
  rendered as horizontal split bars. Honest representation of
  "how many active offers" without faking exchange semantics.

UI copy explicitly explains that Morphit is P2P with negotiated
terms and that each listing has its own constraints — so users
understand what they're looking at.

### APR computation

`computeBlurtVestingApr(dgp)` is a pure helper that takes the
chain's `DynamicGlobalProperties` and returns the current
APR for staked BLURT (Blurt Power) as a percentage.

Constants baked in from Blurt chain config:

- Inflation start: 9.5% annual.
- Decay: 1 basis point per ~250,000 blocks (4 micro-bps/block).
- Floor: 0.95%.
- Vesting share of inflation: 75%.

Computed once per `MyBalanceCard.refresh()` cycle (60s) using
the DGP that was already fetched for BP/MANA — no extra RPC
call. Display: "Currently earning N.NN% APR" sub-line under BP.

Per the user's note "ask the chain every day" — the inflation
rate drifts by sub-basis-points per day, so a 24h cache would
work, but the computation is so cheap (a few floating-point
ops) that we just recompute every refresh. Same end-user
experience.

### Search-input parser

Pure helper `parseSearchInput(raw)` returns one of:
`{kind: 'account', account}`, `{kind: 'txid', txid}`,
`{kind: 'block', blockNumber}`, or `{kind: 'unknown', raw}`.

Strict classification:

- Strips leading `@` (so `@alice` and `alice` are equivalent).
- Account name: lowercase, starts with letter, length 3–16.
- Block number: pure digits, positive, less than
  `Number.MAX_SAFE_INTEGER`.
- Txid: 40 hex chars (the Blurt format; not 64 BTC/XMR).
- Anything else → `unknown`. Better to fail explicitly than
  guess wrong.

The submit handler dispatches to the right route based on the
discriminated kind.

### Param matchers

SvelteKit param matchers reject malformed URLs at routing time:

- `account` (existing): the standard Blurt account regex.
- `blocknum` (new): `/^[1-9][0-9]{0,18}$/`.
- `trxid` (new): `/^[0-9a-f]{40}$/` lowercase only.

A garbage URL like `/explorer/block/abc` 404s before any RPC
call.

### Op-decoration helper

Pure helper `decorateOp(opName, opBody)` returns
`{kind, labelKey, isMorphitOp}`. Uses `OP_IDS` from the existing
config. Smoke covers all 21 decoration kinds plus the
fallthrough cases.

`isMorphitOp` drives a tinted background on Morphit-specific op
labels — visual signal that this op is part of Morphit's
protocol rather than generic Blurt activity.

## Consequences

### Positive

- Closed the "where's the explorer" gap. The project now has a
  user-facing surface that demonstrates "everything is on chain"
  rather than just claiming it.
- Cross-chain links reduce friction in completed-trade UX. A
  buyer who paid via BTC sees a one-click "View on explorer"
  link to mempool.space.
- APR display gives stake-holders concrete feedback on what
  their BP earns — was previously invisible.
- Activity stats give an honest "how active is this instance"
  signal without faking exchange semantics.
- Reuses the chain-direct-not-indexer posture from ADR-0019,
  consistent with the project's trust model.

### Negative

- The middle-ground explorer can't render the long tail of
  Blurt op types beautifully. Users who hit, say, an
  `escrow_transfer` op see raw JSON. The fallback link to
  `blocks.blurtwallet.com` mitigates but doesn't eliminate the
  rough edge.
- The activity page caps orderbook fetch at limit:100. If the
  ecosystem grows past that for one (asset, side), the
  histogram undercounts. Acceptable for early launch;
  documented in the component for future expansion.
- Volume is an ESTIMATE — the chain doesn't carry exact fill
  amounts on feedback ops. We label this clearly in the UI but
  it's still an asterisk on what looks like a precise number.
- The trust posture for explorer reads is "trust the RPC node"
  same as the rest of the app. A malicious RPC could lie about
  account balances, op history, etc. Detection is best-effort
  (the account-name guard catches one class). Same posture as
  pre-Batch-K and not regressed.
- Long-running tabs accumulate ops in memory unboundedly.
  Acceptable for practical use; tab close clears it.

### Trade-offs explicitly considered

- **Build a generic Blurt op renderer vs middle-ground.**
  Rejected the generic renderer for scope reasons; the long
  tail of op types doesn't materially help Morphit users. The
  middle-ground covers the 95% case beautifully.
- **WebSocket push vs polling.** Per the user, polling is
  fine. Polling is also simpler, doesn't require a
  streaming-RPC plugin (not all Blurt nodes expose one), and
  visibility-aware polling is gentle on chain RPC bandwidth.
- **Depth chart vs listings histogram.** Pushed back on the
  user's "depth chart" framing because Morphit isn't a
  matching engine. User accepted volume + listings-histogram
  alternative.
- **Indexer endpoint vs chain-direct for explorer reads.**
  Chose chain-direct for everything except the activity-page
  volume aggregation (which needs SQL JOIN). Same posture as
  ADR-0019.
- **APR cache cadence.** Considered 24h cache, decided to
  recompute every refresh (60s) — math is trivial, no extra
  RPC call needed.

## Implementation

- `apps/web/src/lib/blurt/apr.ts` — pure APR computation.
- `apps/web/src/lib/explorer/urls.ts` — external + internal
  explorer URL builders with strict input validation.
- `apps/web/src/lib/explorer/search.ts` — search-input parser.
- `apps/web/src/lib/explorer/decorate.ts` — op-decoration
  helper.
- `apps/web/src/lib/explorer/listingsHistogram.ts` — pure
  aggregator for the listings bar chart.
- `apps/web/src/lib/blurt/client.ts` — added `getBlock` +
  `getTransaction` methods + types.
- `apps/web/src/lib/indexer/client.ts` — added
  `getActivityVolume` wrapper and types.
- `apps/indexer/src/api/activity.ts` — `/v1/activity/volume`
  endpoint with three windowed SQL aggregations.
- `apps/web/src/params/{blocknum,trxid}.ts` — route matchers.
- `apps/web/src/routes/explorer/+page.svelte` — search landing.
- `apps/web/src/routes/explorer/account/[name=account]/+page.svelte`
  — account view with 5s polling.
- `apps/web/src/routes/explorer/block/[num=blocknum]/+page.svelte`
  — block detail.
- `apps/web/src/routes/explorer/tx/[id=trxid]/+page.svelte` —
  tx detail with show/hide raw JSON per op.
- `apps/web/src/routes/explorer/activity/+page.svelte` —
  trading activity page.
- `apps/web/src/lib/components/MyBalanceCard.svelte` — APR
  sub-line under BP.
- `apps/web/src/lib/components/ChatMessage.svelte` — funds_sent
  pill "View on explorer" link routing per asset.
- `apps/web/src/routes/+layout.svelte` — footer link added.
- `apps/web/src/routes/my/orders/+page.svelte` — header link
  to user's account on explorer.
- `apps/web/src/lib/utils/faqIndex.ts` — `block_explorer` FAQ
  key registered.
- Smokes:
  - `apr-smoke.ts` — 13 scenarios (inflation curve, APR
    formula, formatter).
  - `explorer-urls-smoke.ts` — 21 scenarios (URL builders +
    injection rejection).
  - `explorer-search-smoke.ts` — 20 scenarios (parser
    classification + edge cases).
  - `explorer-activity-smoke.ts` — 19 scenarios (histogram
    aggregation + decorateOp).
- i18n: 109 new keys × 10 locales = 1090 strings (88 page
  keys + 21 op labels). Drift = 0.
- Audit doc: `docs/audit/2026-04-29-batch-k-explorer.md`.

## Open questions / future work

- **Generic Blurt op renderer**: every Blurt op type with
  properly formatted fields, replacing raw-JSON fallback.
  Substantial work; deferred until users complain.
- **Real depth/price-vs-market display**: requires a market-
  price feed (currently no canonical source in the Blurt
  ecosystem). Deferred.
- **Tx-by-id without tx-index plugin**: walk blocks ourselves
  to find a tx. Quadratic if naive; needs a sensible search
  bound. Deferred.
- **Activity page cap > 100 listings per side**: if the
  ecosystem grows, expand to paginated fetch + accumulate.
  Deferred.
- **Long-running tab memory cap on /explorer/account**: cap
  the `ops` array at, e.g., 1000 entries with "view earlier
  on fallback" affordance. Deferred until reports.