Indexer–protocol pairing (dogex, web-com, command.dog)

Audience: spec authors, indexer maintainers (dogex), API backends (command.dog), and marketplace frontends (web-com).
Status: Informative coordination doc — not a substitute for each protocol’s spec.md.

Why this document exists

Dogenals wins when three layers stay aligned:

1. On-chain rules — what wallets can inscribe or put in OP_RETURN / witness envelopes.
2. Normative specs — deterministic validation any honest indexer can code.
3. Read APIs & UIs — query shapes, pagination, and display that never imply stronger guarantees than the spec.

Drift between (2) and (3) is how ecosystems get “spec-by-indexer” reputations. This doc is a checklist to keep implementations honest.

Repository roles (typical dogeco checkout)

Greenfield: public domains ≠ launched product. Do not keep dual market/DEX indexes “for production we never shipped.” Map: TWO_LAYER_BACKEND.md.

Paths are sibling folders on disk, not git submodules.

Truth model

Spec author obligations (keep indexers honest)

Every normative rule in a protocol spec SHOULD be:

• Implementable from chain data (or explicitly labeled policy / indexer MAY if not on-chain).
• Testable — prefer JSON vectors under spec/protocols/<name>/vectors/ (see ÐMP, ÐWhisper patterns).
• Clear on ordering — FCFS, first-valid-in-tx, reorg behavior: ambiguity becomes a fork.
• Explicit on “ignored” vs “invalid” — indexers need stable categories for spam, malformed payloads, and deprecated versions.

When adding a new protocol (e.g. ÐGPS orientation in spec/protocols/dgps/README.md, or Ðocial in spec/protocols/dsocial/), add a companion checklist issue or PR section: vectors, API sketch, and dogex / command.dog touchpoints.

Indexer obligations (dogex)

• Determinism — same chain + same spec version ⇒ same derived state (modulo explicit optional indexes).
• Reorg safety — rollback/replay via CF_UNDO per block; document which CFs are authoritative vs cache.
• Versioned HTTP APIs — stable JSON fields; additive changes > silent renames (/api/doginals/*, /api/rare-koinu/*, /openapi.json).
• Conformance — run or mirror reference vectors from spec/implementations/ and protocol vectors/ where they exist.
• Documentation — dogex/docs/PROTOCOLS.md, LEGACY_PARITY.md, FIRST_FULL_INDEX.md; link back to dogenals/spec/protocols/....

Reference implementation: dogex (dogexd --doginals). Legacy kabosu and dog indexers are archived.

command.dog API obligations

• Stay in specialty — realtime, jobs, mintpad, Grok, product glue. No new dual-index / DXD-Postgres / listings-truth routes (delete or 410 when touched).
• Parse, don’t legislate — ephemeral parse helpers (WatchDoge, etc.) match dogenals/spec/; do not invent validity rules.
• OpenAPI — keep x-implementation-status honest (stub vs live product surface).

web-com marketplace obligations

• Data source switch — VITE_MARKETPLACE_DATA_SOURCE / VITE_MARKETPLACE_API_BASE (see web-com/README.md); mock data must be obviously non-authoritative in UI where it could be confused with chain truth.
• No silent spec drift — if the UI introduces a new field or flow tied to a protocol, link or comment the spec path in the PR.
• Proxies — server.ts / vite.config.ts same-origin proxies (/__indexer, /__commanddog, …) exist to avoid CORS; they do not change validation rules.

New-protocol rollout checklist

Use this when shipping something like ÐGPS end-to-end:

1. spec/protocols/<name>/ — README + spec.md (when ready) with MUST/SHOULD/MAY.
2. Vectors — JSON fixtures for happy path + common failures.
3. dogex — parser + RocksDB CF + API routes + PROTOCOLS.md row.
4. command.dog — only if mempool parse, RPC helper, or session flow needs it.
5. web-com — env-driven reads; no hardcoded indexer-only semantics.
6. docs/INDEX.md + root spec/README.md protocol table — navigation updated in the same change window.

Related docs

• implementations/README.md — reference validators and indexer-shaped templates.
• CONTRIBUTING.md — repo-wide contribution expectations.
• guides/indexer-debug-playbook.md — practical debugging.
• dogex/docs/OWNERSHIP.md · command.dog/api/docs/OWNERSHIP.md
• TWO_LAYER_BACKEND.md — greenfield specialty map
• dogex/docs/LEGACY_PARITY.md — archived code-lineage checklist only
• MONOREPO.md — monorepo vs siblings

Related implementations (protocol touchpoints)

Maintainers: when dogex or command.dog gains a new Dogenals protocol, add a one-line cross-link here under “Related implementations” in the same PR as the spec or README update.