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:
- On-chain rules — what wallets can inscribe or put in
OP_RETURN/ witness envelopes. - Normative specs — deterministic validation any honest indexer can code.
- 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)
| Piece | Typical path | Role |
|---|---|---|
| Standards | dogenals/spec/ | Canonical spec.md, vectors, comparisons — source of truth for rules. |
| Marketplace | dogenals/web-com/ | SPA; reads indexer/APIs via env (VITE_MARKETPLACE_*, proxies in server.ts). |
| Indexer | dogeco/dogex/ | Chain scan → RocksDB InscriptionIndex → HTTP APIs (Doginals, ÐMP, Dogetag, Charms, Rare Koinu, …). |
| Backend | dogeco/command.dog/api/ | Core RPC, broadcast, WatchDoge, Ð𝕏 orchestration, parsers that mirror spec/ rules where applicable. |
| Archived | dogeco/dog/, dogeco/kabosu/ | Legacy ord CLI + Postgres indexer — archived; parity checklist: dogex/docs/LEGACY_PARITY.md. |
Paths are not git submodules; they are sibling folders on disk. CI may clone only one repo — each README states its own clone URL.
Truth model
| Layer | Holds |
|---|---|
| Dogecoin L1 | Authoritative bytes: txs, witnesses, OP_RETURN. |
Dogenals spec.md | What those bytes mean and what is valid / invalid. |
| dogex indexer | Materialized view: fast queries, aggregates, spatial indexes — must be recomputable from chain + spec. |
| command.dog | Operational services (RPC, mempool WS, image gen) + parsers that should not invent rules beyond spec for “what counts as Dogenals”. |
| web-com | Presentation + client validation for UX only; never the final word on validity. |
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), 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_UNDOper 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 protocolvectors/where they exist. - Documentation —
dogex/docs/PROTOCOLS.md,LEGACY_PARITY.md,FIRST_FULL_INDEX.md; link back todogenals/spec/protocols/....
Reference implementation: dogex (dogexd --doginals). Legacy kabosu and dog indexers are archived.
command.dog API obligations
- Parse, don’t legislate — e.g.
POST /v1/dogenals/parseand WatchDoge paths should match published Dogenals parsing rules fromdogenals/spec/. When behavior changes, spec + Rust should move together. - Separation — RPC proxy, broadcast, and Grok/Ð𝕏 flows are not a replacement for a full marketplace indexer; they complement dogex-style services.
- OpenAPI — keep
x-implementation-status(or equivalent) honest so clients know what is stub vs production.
web-com marketplace obligations
- Data source switch —
VITE_MARKETPLACE_DATA_SOURCE/VITE_MARKETPLACE_API_BASE(seeweb-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.tssame-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:
-
spec/protocols/<name>/— README +spec.md(when ready) with MUST/SHOULD/MAY. - Vectors — JSON fixtures for happy path + common failures.
- dogex — parser + RocksDB CF + API routes +
PROTOCOLS.mdrow. - command.dog — only if mempool parse, RPC helper, or session flow needs it.
- web-com — env-driven reads; no hardcoded indexer-only semantics.
- 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/LEGACY_PARITY.md — archived
dog/kabosuparity gate. - MONOREPO.md — what lives inside this Git repo vs siblings.
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.