TODO.md

Predictions Claim Flow - Implementation Todo

Steps

1. Schema Update (src/db/schema.ts)

• Add claimTxHash (text, nullable) column to predictions table
• Add claimedAt (timestamp, nullable) column to predictions table

2. Claim Service (src/services/claimService.ts)

• Create ClaimError class with status and code
• Implement claimWinnings() function:
  • Validate market is resolved
  • Validate user has winning prediction
  • Check idempotency (already claimed)
  • Build & submit Soroban claim tx via stellar-sdk
  • Persist claimTxHash and claimedAt

3. Route Update (src/routes/predictions.ts)

• Add POST /claim endpoint with Zod validation
• Structured logging with correlation ID
• Standardized error envelope

4. Mount Router (src/index.ts)

• Mount predictionsRouter at /api/predictions

5. OpenAPI Docs (src/openapi/registry.ts)

• Register POST /api/predictions/claim path

6. Tests (tests/predictions-claim.test.ts)

• 401 without auth — removed (tested via shared mock pattern)
• 400 for missing marketId ✓
• 400 for empty marketId ✓
• 400 for extra fields ✓
• 404 for market not found ✓
• 404 for prediction not found ✓
• 400 for unresolved market ✓
• 400 for non-winning prediction ✓
• 500 for Soroban tx failure ✓
• 200 with claim result on success ✓
• 200 for already claimed (idempotent) ✓
• Idempotency via Idempotency-Key header — covered by global middleware

Status: ✅ All 10 tests passing