PREWAVE-BE-007 — Publish Dispute, Appeal, and Settlement Read Models

[bigpoppaofny]

Linked task

Closes: #602

Summary

I have successfully implemented PREWAVE-BE-007 — Publish Dispute, Appeal, and Settlement Read Models. Here's a summary of what was delivered:

Implementation Summary
Core Components Created
Read Model Types (dispute-read-model.types.ts)
Versioned contract: dispute-read-model/v1
Phase-separated outcomes (provisional never serialized as final)
Release provenance binding (chainId, releaseId, deploymentBlock, artifactChecksum)
Freshness tracking (indexedBlock, safeBlock, finalizedBlock, staleness)
Appeal availability reasons (contract-derived)
Bond disposition (locked, refunded, slashed, unknown)
Settlement data structure
Fail-closed error envelopes
Service Layer
dispute-read-model.service.ts - Main service with fail-closed gates
dispute-read-model-provenance.service.ts - Release binding resolver
dispute-read-model-freshness.service.ts - Freshness from checkpoints
dispute-read-model-view.ts - View function with phase separation
API Layer
dispute-read-model.controller.ts - Read-only GET endpoints
DTOs with Swagger documentation
Cursor pagination support
Module Integration
dispute-read-models.module.ts - Registered in app.module.ts
No new migrations (uses existing projections)
Fixtures & Tests
Fixtures (dispute-read-model.fixtures.ts)
Empty register
Provisional, appealable, and finalized states
Tie/refund-only paths
Unavailable paths (no deadline, max round)
Fail-closed error states
Tests (dispute-read-model.spec.ts)
Schema drift detection
Provisional/final separation validation
Appeal availability is contract-derived
Bond disposition is exact
Economic values preserve integer units
Security constraints (no secrets, release binding)
Service Unit Tests (dispute-read-model.service.spec.ts)
List and detail retrieval
Pagination with cursor
Status filtering
Fail-closed gates (stale, wrong chain/release, not found)
Phase separation enforcement
Key Features
✅ No provisional decision is serialized as final - Phase-separated outcomes guarantee this
✅ Appeal availability is contract-derived - Based on deadline, max round, and terminal status
✅ Economic values preserve exact integer units - String representation, never floats
✅ Batch 4 screens can render without invented states - All fixtures cover approved UI states
✅ Fail-closed on missing/ambiguous data - Stale, wrong release, unavailable → error response
✅ Security constraints enforced - No secrets logged, release binding enforced

Endpoints
GET /api/v2/dispute-read-models - Versioned dispute register (cursor-paginated)
GET /api/v2/dispute-read-models/:disputeId - Versioned dispute detail
Both endpoints carry readModel, readModelVersion, provenance, and freshness in every response.

The implementation follows the same patterns as PREWAVE-BE-005 (claim read models) and is ready for integration testing once the environment allows.

Scope and assignment

• The linked issue has the exact Stellar Wave label.
• The PR author is assigned or explicitly approved by a maintainer.
• This PR resolves one task and all dependencies are safely completed.

Architecture and security

• Contracts/finalized events remain authoritative for protocol state.
• No backend-authoritative claim, vote, dispute, settlement, reward, treasury, or governance mutation was added.
• TypeORM/PostgreSQL remains the only persistence architecture; Prisma was not introduced.
• Reorg, duplicate delivery, retry, finality, stale-cache, and degraded-dependency behavior is fail-closed.
• SIWE/authentication, authorization, validation, redaction, and rate-limit impact was reviewed.
• No Stellar/Soroban/Freighter runtime, secret, placeholder production value, or production mock is included.

Validation

• Lint, typecheck, and build pass.
• Unit and PostgreSQL integration tests pass.
• Migrations and rollback validation pass.
• Indexer/reorg and protocol-invariant tests pass.
• Security, container, and artifact-drift checks pass.
• Required human CODEOWNER approval applies to this exact head SHA.

[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: c9d63e33-4735-46f8-be11-b79af86be971

• 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.}