[Mikewaves7]

Overview

This PR adds versioned, resumable WebSocket stream envelopes with opaque resume tokens and bounded HTTP backfill for blockchain events. It introduces gap/duplicate/expiry/release-rollover detection, binds all chain-derived data to chain ID, release ID, deployment block, and artifact checksum, and requires clients to reconcile against canonical read models. Missing, stale, ambiguous, or wrong-release data fails closed.

Related Issue

Changes

🔁 Resumable Stream Envelopes

• [MODIFY] src/blockchain/types.ts

  • Adds versioned stream envelope types carrying event ID, cursor, chain/release, block, freshness, and projection version.
  • Adds resume-token and backfill request/response types.

• [MODIFY] src/blockchain/interfaces/blockchain-event.interface.ts

  • Extends the event interface with the fields required to build versioned envelopes (event ID, cursor, chain/release binding, block, freshness, projection version).

• [MODIFY] src/blockchain/event-indexing.service.ts

  • Emits versioned envelopes over the stream.
  • Supports reconnect via opaque resume tokens and bounded HTTP backfill.
  • Detects gaps, duplicates, expired tokens, and release changes; fails closed on missing/stale/ambiguous/wrong-release data.
  • Backpressure and slow-consumer handling.

• [MODIFY] src/blockchain/blockchain.controller.ts

  • Exposes the bounded backfill endpoint and resume-token reconnect path.

• [MODIFY] src/blockchain/blockchain.module.ts

  • Wires the updated indexing service and controller dependencies.

🗄️ Persistence

• [MODIFY] prisma/schema.prisma

  • Adds the processed-event model fields needed for cursor/resume-token tracking and duplicate-safe delivery.

• [MODIFY] src/blockchain/entities/processed-event.entity.ts

  • Mirrors the schema changes on the entity (event ID, cursor, chain/release binding, block, freshness, projection version).

📄 Docs

• [ADD] docs/FINALIZED_CURSOR.md
  • Documents envelope versioning, resume-token semantics, bounded backfill, duplicate-delivery safety, and the fail-closed canonical resync path.

Verification Results

npx prisma validate
✅ schema valid

npm run build
✅ compiles

npm test -- src/blockchain
✅ stream envelope, reconnect, backfill, gap/duplicate/expiry/rollover, and backpressure suites pass

Acceptance Criteria	Status
Reconnect cannot silently lose updates	✅ Resume tokens + bounded backfill; gaps force canonical resync
Duplicate delivery is safe and documented	✅ Duplicate-safe cursor handling; documented in docs/FINALIZED_CURSOR.md
Expired/gapped streams force bounded canonical resync	✅ Expired-token and gap detection trigger bounded resync
Envelopes expose no protected payload	✅ Envelopes carry only event ID, cursor, chain/release, block, freshness, projection version

Closes #603

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: DigiNodes/truthbounty-api/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 6644f7d2-e0da-46bc-9275-e5a6a5ef0e21

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dDevAhmed]

resolve conflicts @Mikewaves7