Indexer Debug Playbook (Doginals + Dogenals)

Use this playbook when an indexer “runs” but output looks wrong, missing, or inconsistent across implementations.

1) Fast triage checklist

1. Confirm network mode (mainnet/testnet/regtest).
2. Confirm first inscription scan height is network-correct.
3. Confirm parser recognizes all required markers:
   • Era1 ord
   • Era1 dog (script_sig)
   • Era2 witness dog envelope
4. Confirm unknown dog versions are indexed as unsupported, not dropped.
5. Confirm reorg rollback is enabled and undo state is written.

2) Known high-signal failure modes

• Wrong start height: indexer appears to work but misses early inscriptions.
• Marker mismatch: parser only supports ord and silently ignores dog.
• Version handling bugs: parser accepts v1 but drops vN without metadata.
• CBOR decode brittleness: malformed payload causes transaction-level abort instead of localized failure.
• Reorg drift: state diverges from tip after short forks.

3) Minimal reproducible tests

Always keep three fixtures in CI:

1. Witness dog v1 fixture (OP_FALSE OP_IF "dog" OP_1 <cbor> OP_ENDIF)
2. Era1 script_sig dog fixture (PUSH("dog") PUSH(version) PUSH(cbor...))
3. Unknown dog version fixture (dog + unsupported version + opaque payload)

Each fixture should assert:

• Parsed marker path
• Parsed or preserved payload
• Final indexed representation

4) PowerShell-first runtime debugging

Use structured logs and filtered output to avoid noise.

$env:RUST_LOG="dogex::indexer=debug,dogex::indexer::envelope=trace,dogex::indexer::updater=debug"
cargo run --bin dogexd -- --network mainnet *>&1 | Tee-Object .\indexer-debug.log

Quick scans:

Select-String -Path .\indexer-debug.log -Pattern "reorg|dog|ord|unsupported|error|panic"
Select-String -Path .\indexer-debug.log -Pattern "height|next_sequence_number|last_height"

If a run is long, sample around suspicious heights:

Select-String -Path .\indexer-debug.log -Pattern "height=4600000|height=4753897|height=6142069"

5) State validation snapshots

After each major parser change:

1. Index a small fixed window.
2. Export deterministic summary (counts by module/marker/version).
3. Compare against prior known-good snapshot.

Recommended summary fields:

• last indexed height
• total inscriptions
• counts by marker (ord, dog, Ð:*)
• counts by dog version (1, unsupported)
• rollback count / last rollback height

6) Cross-indexer parity workflow

For parity checks against a reference implementation:

1. Pick a fixed block window.
2. Compare transaction-level parse results first.
3. Compare final state second.
4. Investigate first mismatch only; do not batch-debug many mismatches at once.

7) Operational recommendations

• Keep parser failures localized to the offending envelope or tx.
• Never let a single malformed envelope stop full block indexing.
• Attach enough context in logs: height, txid, input_index, path (ord/dog), version.
• Use explicit feature flags for experimental envelope branches.

8) Definition of done for parser changes

• Unit tests: new happy path + malformed path + unknown-version path.
• Integration test: one fixed block-window run with deterministic summary.
• Reorg test: apply and roll back at least one fixture block.
• Docs updated: spec + vectors + this playbook.