Skip to content

Implement adaptive retry engine with per-error-class strategy, circuit breaker, and telemetry integration #185

@Kingsman-99

Description

@Kingsman-99

Description

Replace the current hardcoded retry logic in StellarSplitClient with a configurable adaptive retry engine that applies different strategies per error class, integrates with the existing TelemetryCollector, and includes a circuit breaker that opens after N consecutive failures.

Acceptance Criteria

  • Create src/retryEngine.ts with RetryEngine class accepting RetryConfig
  • RetryConfig supports per-error-class strategies: { transient: RetryStrategy, rateLimit: RetryStrategy, contract: RetryStrategy } where RetryStrategy = { maxAttempts: number, initialDelayMs: number, backoffMultiplier: number, jitterMs?: number }
  • Error classification: network/timeout errors → transient; HTTP 429 → rateLimit; Soroban contract errors (Error(Contract, #N)) → contract (never retried)
  • Circuit breaker: after circuitBreakerThreshold consecutive transient failures, circuit opens and all calls fail immediately with "circuit open" for circuitResetMs milliseconds
  • RetryEngine.execute<T>(fn: () => Promise<T>, methodName: string): Promise<T> — runs fn with retry logic and records each attempt via TelemetryCollector.recordMethod
  • StellarSplitClient constructor accepts optional retry?: RetryConfig and uses RetryEngine for all contract-submitting methods (pay, cloneInvoice, release, refund)
  • Circuit state is per-RetryEngine instance (not global)
  • Tests: transient error retries with backoff, contract error not retried, circuit opens after threshold, circuit resets after timeout, jitter produces non-deterministic delays (test range not exact value)

Context

  • Current retry is inline in src/client.ts pay() method — extract and replace
  • TelemetryCollector is in src/telemetryCollector.ts
  • src/circuitBreakerMonitor.ts already exists — integrate or extend rather than duplicate

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestgrantfoxIssue for GrantFox program

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions