Skip to content

Build invoice payment timeline reconstructor from event history #481

Description

@Kingsman-99

Description

Debugging payment disputes or auditing invoice lifecycles requires a chronologically ordered view of every state change and payment event for an invoice, but these events are scattered across Soroban event streams and Horizon payment records. This issue adds a PaymentTimelineReconstructor that aggregates events from both sources, normalizes them into a unified TimelineEntry format, and returns a sorted, deduplicated timeline for a given invoice.

Technical Context

  • New file: src/timeline/PaymentTimelineReconstructor.ts; types: TimelineEntry, TimelineSource, ReconstructedTimeline in src/types/timeline.ts
  • TimelineEntry: { timestamp: number; ledger: number; type: TimelineEventType; data: Record<string, unknown>; source: 'soroban'|'horizon' }
  • TimelineEventType union: 'invoice_created'|'payment_received'|'status_changed'|'recipient_added'|'recipient_rerouted'|'sla_breached'
  • Deduplication uses (ledger, txHash, type) as the composite key to eliminate events that appear in both sources
  • reconstructor.rebuild(invoiceId, options?: { from?: number; to?: number; types?: TimelineEventType[] }): Promise<ReconstructedTimeline> is the primary API

Acceptance Criteria

  • A timeline for an invoice with 3 Soroban events and 2 Horizon payment records returns 5 deduplicated entries sorted by timestamp ascending
  • An event present in both Soroban and Horizon streams appears exactly once in the output (deduplication)
  • from / to ledger range filters exclude entries outside the range
  • types filter returns only entries whose type is in the provided array
  • ReconstructedTimeline includes { totalEvents, sources: { soroban: number; horizon: number }, deduplicatedCount } in its metadata
  • All CI checks (npm test, npm run build, ESLint) pass and the branch has no merge conflicts

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions