Summary
When a deposit fails, debugging requires correlating HTTP request logs, Stellar event processing, DLQ entries, and agent actions. Today there is no request-scoped identifier propagated through the system.
Problem
src/middleware/logger.ts logs method/path/status/duration/IP only:
logger.info(`${req.method} ${req.path}`, {
status: res.statusCode,
duration: `${duration}ms`,
ip: req.ip
})
## Proposed solution
Add correlationIdMiddleware:
Accept incoming X-Request-ID or X-Correlation-ID (validate format/length)
Generate UUID if absent
Attach to req.correlationId and res.locals
Return header on all responses
Extend Winston logger with child logger / default meta { correlationId }
Propagate ID into:
transaction-controller when submitting on-chain ops
stellar/events.ts when processing contract events (store in processed_events metadata or new column)
DeadLetterEvent.payload metadata on failure
agent_logs.inputData for scheduled jobs (job-level correlation ID per run)
Optional Phase 2: OpenTelemetry SDK (@opentelemetry/api) with HTTP + Prisma instrumentation
## Acceptance criteria
Every HTTP response includes X-Request-ID
All request logs include correlationId
Error handler logs include correlationId
Failed Stellar events in DLQ retain originating correlationId when available
Unit tests for middleware (preserves client ID, generates when missing)
Integration test: single request ID appears across HTTP log + downstream mock handler
README documents header for client integrators
Response shape (non-breaking)
Optionally include in error JSON:
{
"error": "Internal server error",
"requestId": "uuid"
}
Summary
When a deposit fails, debugging requires correlating HTTP request logs, Stellar event processing, DLQ entries, and agent actions. Today there is no request-scoped identifier propagated through the system.
Problem
src/middleware/logger.tslogs method/path/status/duration/IP only: