Overview

Establish the Projection Readiness Gate as an independently reviewable V2 backend work item. This task strengthens the event-sourced read model and its ability to reproduce canonical Optimism/EVM state.

Problem Context

TruthBounty treats deployed Optimism/EVM contracts and canonical chain events as protocol authority. The API is a deterministic indexing, projection, authentication, and delivery layer; it must never invent, mutate, or override protocol truth. This boundary must remain explicit under failures, retries, reorgs, migrations, and degraded dependencies.

Technical Scope

• Define the production design, interfaces, invariants, and failure modes for this task.
• Implement the smallest cohesive backend change needed to satisfy the design.
• Keep chain-derived state reproducible from canonical events and versioned deployment artifacts.
• Add observable, actionable failure reporting with no silent fallback to fabricated state.
• Update operator and developer documentation where behavior or recovery procedures change.

Security and Architecture Requirements

• Optimism/EVM only; do not add Stellar, Soroban, Freighter, or alternate-chain runtime paths.
• Smart contracts and finalized canonical events remain authoritative for protocol state.
• Do not introduce backend-authoritative settlement, rewards, treasury, governance, claim, or dispute mutation.
• Preserve the TypeORM-only persistence boundary; do not add Prisma or a second ORM.
• Fail closed on identity, chain, finality, signature, authorization, configuration, and integrity uncertainty.
• Never commit secrets, live credentials, placeholder production values, or production mocks.

Required Tests

• Unit tests for success, invalid input, boundary conditions, and each documented failure mode.
• Integration tests using PostgreSQL/Redis/RPC dependencies appropriate to the change.
• Reorg, retry, duplicate-delivery, stale-data, and degraded-dependency coverage where applicable.
• Regression tests proving canonical protocol compatibility and no unauthorized mutation path.
• CI evidence for lint, typecheck/build, tests, security scanning, migration checks, and artifact drift.

Acceptance Criteria

• The implementation matches the canonical V2 protocol and repository architecture.
• Behavior is deterministic, observable, and fail-closed where correctness or security is uncertain.
• Required tests execute in CI and pass without skips that conceal required coverage.
• Migrations, schemas, generated artifacts, and documentation are synchronized.
• No unrelated issue is closed and no unrelated refactor is bundled.
• An independent human maintainer approves the exact head SHA when the change is security-sensitive.

Dependencies

V2-BE-099; any referenced contract ABI/address artifact must already be canonical.

Non-Goals

• Changing smart-contract protocol rules.
• Adding alternative-chain runtime support.
• Replacing TypeORM or creating a second persistence architecture.
• Activating this task for contributor assignment before maintainers apply Stellar Wave.

Complexity and Review

• Complexity: high
• Points: 200
• Review: backend maintainer; security/architecture maintainer approval required for sensitive paths.

🏷 Labels

• backend
• complexity-high
• wave-candidate