Skip to content

docs: unify contract event topic naming and stable ID docs for indexer compatibility - #339

Open
eulami wants to merge 1 commit into
BlockDash-Studios:mainfrom
eulami:fix/issue-331-unify-event-docs
Open

docs: unify contract event topic naming and stable ID docs for indexer compatibility#339
eulami wants to merge 1 commit into
BlockDash-Studios:mainfrom
eulami:fix/issue-331-unify-event-docs

Conversation

@eulami

@eulami eulami commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #331

This PR synchronizes event documentation across the contract and backend, ensuring indexers have a single, consistent source of truth for all event schemas.

Problem

The contract defined event topic constants (EVENT_TOPIC_*) and stable event type IDs (ETID_*) in events.rs, but the backend indexer docs and contract README were out of sync with the actual event payload shapes, making it difficult for indexers to correctly parse and route events.

Changes

app/contract/README.md

  • Added Event Topic Namespaces table documenting all 5 domains (TOPIC_ADMIN, TOPIC_DISPUTE, TOPIC_ESCROW, TOPIC_PRIVACY, TOPIC_STEALTH)
  • Added Stable Event Type IDs reference organized by domain with descriptions
  • Added Mandatory Replay Fields documentation (event_type_id, schema_version, ledger_sequence, timestamp)
  • Added Indexer Integration examples for domain filtering, stable ID routing, and deduplication

app/contract/docs/UPGRADE_SAFETY_GATE.md

  • Added stable numeric IDs for upgrade events (ETID_UPGRADE_STARTED=53, ETID_UPGRADE_COMPLETED=54) to event struct documentation
  • Added topic namespace reference (EVENT_TOPIC_ADMIN = "TOPIC_ADMIN")
  • Added cross-reference to contract README for complete schema documentation

app/backend/docs/CONTRACT_EVENTS.md (NEW)

  • Comprehensive 788-line indexer reference document
  • All 40+ event schemas with complete payload definitions (alphabetically sorted keys)
  • Stable ID routing tables organized by domain
  • Topic namespace filtering guide with code examples
  • Deduplication strategy using replay fields
  • TypeScript router implementation example
  • Cross-validation pattern for Horizon API integration
  • Version history table

app/backend/README.md

  • Added Contract Event Ingestion section under Architecture
  • Cross-referenced new CONTRACT_EVENTS.md documentation
  • Linked to contract README for event overview

app/contract/contracts/Folder/src/events.rs

  • Enhanced rustdoc comments for all 5 EVENT_TOPIC_* constants
  • Documented which specific events belong to each namespace
  • Added indexer usage notes and filtering guidance for each topic

Testing

  • Verified all event schemas in CONTRACT_EVENTS.md match the actual struct definitions in events.rs
  • Verified all ETID_* values are correctly referenced
  • Verified payload keys are alphabetically sorted as enforced by the contract's runtime validation
  • Verified all 5 topic namespace constants are documented consistently across all files

Related

…r compatibility

Fixes BlockDash-Studios#331

This change synchronizes event documentation across contract and backend
to ensure indexers have consistent, complete event schema reference.

Changes:
- app/contract/README.md: Added comprehensive event topic namespace table,
  stable event type ID reference (40+ events), mandatory replay fields docs,
  and indexer integration examples
- app/contract/docs/UPGRADE_SAFETY_GATE.md: Added event type IDs for upgrade
  events (ETID_UPGRADE_STARTED=53, ETID_UPGRADE_COMPLETED=54) and topic
  namespace reference
- app/backend/docs/CONTRACT_EVENTS.md: NEW comprehensive 788-line indexer
  reference with all event schemas, payload definitions, stable ID routing
  table, deduplication strategy, and TypeScript implementation examples
- app/backend/README.md: Added Contract Event Ingestion section under
  Architecture with cross-references to event docs
- app/contract/contracts/Folder/src/events.rs: Enhanced rustdoc comments
  for all 5 EVENT_TOPIC_* constants documenting which events belong to each
  namespace and indexer usage patterns

All event schemas now document:
- Stable numeric event type IDs (never change across releases)
- Topic namespace filtering (TOPIC_ADMIN, TOPIC_DISPUTE, TOPIC_ESCROW, etc.)
- Mandatory replay fields (event_type_id, schema_version, ledger_sequence, timestamp)
- Alphabetically sorted payload keys
- Deduplication strategies
- Cross-validation approaches
@MaryammAli

Copy link
Copy Markdown
Contributor

@eulami
this is not the issue description
read the issue description and implement please

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

unify contract event topic naming and stable ID docs for indexer compatibility

2 participants