soroban-event-dlq

A reusable dead-letter queue for reliably delivering Stellar/Soroban events — contract events from an indexer, Horizon streaming events, or similar — via webhooks, with pluggable storage.

Handles retry scheduling, backoff, and failure tracking, without dictating what database or framework you use to persist failed deliveries.

Why

Soroban indexers and backends that push contract events to consumers over HTTP webhooks need reliable retry and dead-letter handling — the same problem shows up repeatedly across different Stellar backend projects, but is usually reimplemented from scratch each time.

Install

npm install soroban-event-dlq

Usage

import { EventDispatcher, DlqStorageAdapter } from "soroban-event-dlq";

// Implement DlqStorageAdapter against your own database (Postgres,
// Redis, etc.), or use the built-in InMemoryAdapter for testing.
const dispatcher = new EventDispatcher(myStorageAdapter, {
  maxRetries: 5,
  backoffStrategy: (attempt) => attempt * 5000, // 5s, 10s, 15s...
});

// Send a webhook; failures are automatically queued for retry
await dispatcher.dispatch("webhook-1", "https://consumer.example.com/hook", eventPayload);

// Call this on a schedule (cron, worker loop) to process due retries
await dispatcher.processRetries();

Setup on a new machine

git clone https://github.com/Israel-Light-Labs/soroban-event-dlq.git
cd soroban-event-dlq
npm install
npm test
npm run build

Status

Core dispatch/retry logic and the in-memory adapter are covered by 7 passing unit tests (npm test), verified against real Jest output. Build produces both compiled JS and .d.ts type declarations in dist/.

Roadmap

• Real-world storage adapter examples (Postgres, Redis)
• Configurable retry-exhaustion webhook/alert (notify when a delivery is permanently abandoned)