Feature: Add Outbox Event Relay and Handler Registry

[3m1n3nc3]

Description

The outbox delivered by #122 has a complete producer side — transactional writes, typed status, leasing, backoff, dead-letter, and versioned payload validation — but only one consumer. src/workers/wallet-provisioning.worker.ts is bound directly to WalletProvisioningOutboxHandler, so it drains only wallet provisioning work. event-schema.ts already registers UserCreated alongside the wallet events, and nothing consumes it: those rows are written inside the request transaction and then stay PENDING forever. Every new domain event today needs its own bespoke worker process.

Add a single relay that leases any pending outbox event and dispatches it by eventType to registered handlers, so domains subscribe to events instead of shipping a worker each.

File Location

learnault-api/src/lib/transactions/, learnault-api/src/jobs/, learnault-api/src/workers/, and learnault-api/docs/domains/REQUEST_AND_EVENT_FLOWS.md

Design Reference

API Roadmap Phase 1.1: Add Outbox Event Relay and Handler Registry. Consumes the primitives delivered by #122.

Dependencies

• Status: Blocked
• Blocked by: Feature: Add Transaction Outbox and Job Delivery Foundation #122 (Add Transaction Outbox and Job Delivery Foundation) — done; Feature: Add Scheduled Background Job Runner #152 (Add Scheduled Background Job Runner)
• Blocks: Later phase domain events for rewards, credentials, and notifications

Tasks

• Define a handler interface keyed by eventType and eventVersion
• Add a registry that rejects duplicate registrations and unknown event types at startup
• Build a relay that leases pending events, dispatches by type, and records each JobAttempt
• Re-register the wallet provisioning handler through the registry and retire its bespoke worker
• Add a UserCreated handler so the already-emitted event stops accumulating unconsumed
• Mark events PUBLISHED only when every registered handler for that type succeeds
• Route exhausted events to dead-letter and add an operator replay path
• Document the subscribe-to-events flow for new domains

Acceptance Criteria

• A new domain event needs a registered handler, not a new worker process
• UserCreated events are consumed and no longer accumulate in PENDING
• An event with no registered handler fails loudly at startup rather than silently stalling
• A failing handler retries with backoff and dead-letters without blocking other event types
• Replayed dead-letter events produce no duplicate side effects

Verification Evidence

• Attach relay logs showing dispatch by type, a dead-lettered event, and a clean replay

Difficulty

Advanced

[Chongai-Cli]

Hello, can i be assigned to this issue?

[ValJnr-dev1]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.

[LeoRicch]

I have 5+ years of software development experience with strong skills in TypeScript, Node.js, backend architecture, event-driven systems, job queues, and testing.

I can implement the outbox event relay and handler registry, including typed handler registration, leasing, dispatching, retries, dead-lettering, replay safety, and the UserCreated handler while retiring the bespoke wallet worker.

I’ll ensure failures are isolated by event type and add the required tests and verification evidence.

I’m ready to take ownership of this issue and deliver a reliable, well-tested implementation. Please assign it to me.

[Santia2004]

Hi @maintainer! I'd like to work on this issue.

I have checked the requirements and can implement the proposed solution. Could you please assign it to me? Thanks!

[Ezeh20]

Hi, I’m a full-stack developer and I’m interested in working on this issue. I’d be happy to help implement the event relay and handler registry.