feat(ingestion): add schema versioning, decoder registry, raw fallbac…

[wavyboy-build]

Summary
This PR introduces robust event schema versioning, graceful raw payload fallbacks, a centralized decoder registry, and RPC startup capability verification for NotifyChain. Together, these updates eliminate scattered decoding conditionals, prevent ingestion pipeline crashes on unfamiliar contract deployments, and ensure early detection of incompatible RPC node configurations.

Key Changes

1. Contract Event Schema Versioning & Compatibility
   Schema Resolution: Associated supported event schemas with contract versions to enable deterministic version checking per contract.

Structured Diagnostics: Introduced structured error diagnostics when encountering unsupported or mismatched schema versions.

Testing: Added test coverage for schema compatibility validation and diagnostic reporting.

2. Fallback & Inspectability for Unknown Contracts
   Raw Event Retention: Preserved source identifiers (contract address, block, tx hash) and original raw payloads for unrecognized or newly deployed contracts.

API Distinction: Updated the event data model and API responses to explicitly distinguish between decoded and undecoded (raw) events.

Testing: Added integration tests verifying that unfamiliar contract events pass through the pipeline without data loss.

3. Centralized Event-Decoder Registry
   Registry Pattern: Replaced scattered conditional/switch statements with a modular DecoderRegistry allowing decoders to be registered independently.

Resilient Ingestion: Ensured unknown event types return fallback raw objects instead of throwing exceptions or disrupting pipeline ingestion.

Testing: Added unit tests covering decoder registration, dynamic lookup, and unknown event handling.

4. RPC Startup Capability Checks
   Fail-Fast Validation: Implemented pre-flight RPC endpoint capability checks on service startup to verify required RPC methods and response features.

Actionable Errors: Configured explicit, actionable diagnostic messages when an endpoint is missing required capability support.

Testing: Added isolated mock unit tests for startup capability validation.

Acceptance Criteria Verification
[x] Schema versions can be resolved per contract with structured diagnostics on mismatches.

[x] Unknown events retain source IDs and raw payloads while distinguishing decoded vs. undecoded states.

[x] Decoders register independently; ingestion gracefully handles unknown events.

[x] Service performs testable RPC startup checks and fails fast with actionable errors if capabilities are missing.

Closes #933
Closes #935
Closes #936
Closes #937

[drips-wave]

@wavyboy-build Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits