morphit/docs/BATCH-PROFILES-DESIGN.md

# Batch-profile endpoint — design

**Status:** ✅ SHIPPED.  Both sessions complete:
session 1 (indexer-side `GET /v1/profiles?accounts=...`)
landed at `apps/indexer/src/api/profiles.ts`; session 2
(frontend integration via `getProfilesBatch()`) at
`apps/web/src/lib/indexer/profileCache.ts`.  Wired into
orderbook, feedback list, profile cross-reference panes.
This file is preserved as the design rationale; the
endpoint is documented under "Public endpoints" in
`docs/API.md`.

**Scope:** add a batch `GET /v1/profiles?accounts=...` endpoint so
pages that render many usernames at once (orderbook rows, feedback
lists, profile cross-reference panes) can fetch their matching
profiles in one round-trip instead of N single `/v1/profiles/:account`
calls.

## Motivation

Users can set custom avatars (SVG or raster, uploaded via settings).
The avatar is stored in `profiles.json_metadata`. Today, only the
profile page (`/@{account}`) reads this — so avatars are invisible
on orderbook rows, feedback lists, and comment bylines, which all
fall back to the heart identicon.

A naive fix (one `/v1/profiles/:account` call per visible account)
is an N+1 query pattern. An orderbook page with 50 rows would make
51 HTTP requests. Unacceptable.

## Design decisions

### Endpoint shape: `GET /v1/profiles?accounts=alice,bob,carol`

- **Method:** GET, not POST. GET is cacheable at both browser and
  CDN layers. Profile data changes rarely (most users update once
  per year or never); cache-friendliness is the whole point.
- **Query string, comma-separated:** fits the largest realistic
  request (100 accounts × ~16 chars = 1600 chars) well under the
  4 KB practical URL limit. Comma is not valid in Blurt account
  names so unambiguous as a separator.
- **Max batch size: 100.** Caps the worst-case query cost and
  prevents a hostile caller from constructing a request that
  would materialize thousands of rows. An orderbook page is
  ~50 accounts; feedback list is ~20. 100 is comfortably above
  both with margin.

### Response shape: object keyed by account

```json
{
  "profiles": {
    "alice": { "account": "alice", "display_name": "...", ... },
    "bob": { "account": "bob", "display_name": "...", ... }
  }
}
```

Rationale: callers can do `response.profiles[account]` directly
without a find-by-key scan on a list. Matches the pattern the
frontend already uses for caches (`Map<account, Profile>`).

### Unknown / missing accounts

**Silently dropped from the response.** If the caller requests
`?accounts=alice,bob,nonexistent`, the response contains `alice`
and `bob` under `profiles`, and `nonexistent` is simply absent.

Rationale:
- Batches should degrade gracefully. A 404 for the whole batch
  because one account is unknown is hostile.
- The frontend already has to handle "no profile for this account"
  (legitimate case: user has a Blurt account but never set a
  display name). Same code path handles "account doesn't exist."
- An explicit "missing" list in the response would be symmetrical
  but adds noise for the 99% case where everything is found.

### Caching

- **`Cache-Control: public, max-age=90, stale-while-revalidate=60`** —
  but ONLY when the batch is COMPLETE (every requested account
  resolved to a profile row).
- **`Cache-Control: no-store` when the batch is PARTIAL** (at least one
  requested account is absent from the response). #2 — an absent
  account is only *provisionally* authoritative: the usual cause is
  indexer lag, in the 1–2 block window after the account broadcast
  its profile op or signed up. Caching that negative result pinned it
  in the **browser's HTTP cache**, which replays it on every load of
  the same URL — so the fresh profile stayed invisible for up to 150s
  and, crucially, **survived a page refresh** (a reload clears the
  client's in-memory cache but not the browser's disk cache). The
  symptom was a display name falling back to `@account` and an avatar
  falling back to the identicon, with refreshing changing nothing.
  Positive results are still cached for the full 90s; only negatives
  are excluded. Mirrors the client's soft-null policy (cp428) and the
  dynamic-data service-worker exclusion (cp324).
- 90 seconds = 90 blocks on Blurt (3s block time). A user who
  updates their avatar waits ~90 seconds for it to propagate via
  the cache to other visitors' orderbook views. That's acceptable
  because the orderbook-row avatar is a nice-to-have, not a
  correctness surface. (The updating user themselves sees it
  immediately: the client re-fetches their own profile with
  `cache: 'reload'` after a confirmed broadcast, bypassing both the
  in-memory and browser HTTP caches.)
- `stale-while-revalidate=60` lets the CDN serve slightly stale
  responses while refetching, keeping p99 latency low.
- Browser cache also honors this; repeated orderbook navigations
  within 90s don't re-request.

### Rate limiting

Uses the existing `ratelimit` middleware (Finding B). Each batch
request costs 1 token regardless of batch size — the max-size cap
(100) already bounds the worst-case abuse. No separate bucket
needed.

### Authentication

None. Profiles are fully public on-chain data. No reason to gate
the endpoint; doing so would break CDN caching.

## Rejected designs

### B. Push avatars inline with `/v1/orderbook`

Rejected in §G during the decision-landing discussion. Reasons
preserved here for durability:

1. Tight-couples orderbook and profile caches. Orderbook changes
   every block (3s); profiles change once a year. Forcing them
   into one response means either the orderbook gets cached too
   aggressively (stale prices) or the profiles too briefly
   (constant refetch of static data).
2. Bloats every orderbook response. 50 rows × 3 KB per raster
   avatar = 150 KB extra per response. CDN bandwidth cost +
   worse p50 latency for every caller, including ones that
   don't care about avatars.
3. Orderbook responses become unique per (user-set)-avatar-state,
   killing the CDN hit rate.

### C. Don't batch — N+1 calls

Rejected because it scales linearly with orderbook size. A user
scrolling an active orderbook with 200 rows would trigger 200 HTTP
requests. Unacceptable.

## Implementation plan

### Session 1 (this session — indexer)

1. Extend `apps/indexer/src/api/profiles.ts` — new handler for
   `GET /` (batch) alongside the existing `GET /:account`.
2. Extend `packages/indexer-client/src/index.ts` with
   `BatchProfilesResponse` type.
3. Add integration tests covering: happy path, empty batch,
   single-item batch, over-limit rejection, mix of known +
   unknown accounts, malformed account name rejection.

### Session 2 (next session — frontend)

1. `getProfilesBatch(accounts[]): Promise<Map<string, Profile>>` in
   `apps/web/src/lib/indexer/client.ts`.
2. Wire into orderbook page: fetch orderbook first, then batch the
   distinct accounts, swap identicons for custom avatars.
3. Same wiring in feedback list, profile cross-reference pane.
4. Client-side in-memory cache with 90s TTL to match server
   `Cache-Control`.

## Open questions parked for session 2

- Do we want client-side deduplication across the 3 consumer
  surfaces? An orderbook view that then navigates to a profile
  would ideally reuse the batch-fetch result. Design in session 2.
- Is it worth a local storage cache to survive page reloads?
  Probably not — 90s TTL plus the in-memory cache handles the
  common "refresh after a minute of inactivity" case.