Repository navigation
Feature: Add Outbox Event Relay and Handler Registry #153
Description
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
eventTypeandeventVersion - 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
UserCreatedhandler so the already-emitted event stops accumulating unconsumed - Mark events
PUBLISHEDonly 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
UserCreatedevents are consumed and no longer accumulate inPENDING- 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
Activity
Chongai-Cli commentedon Aug 27, 2026
Hello, can i be assigned to this issue?
ValJnr-dev1 commentedon Aug 27, 2026
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 commentedon Aug 27, 2026
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
UserCreatedhandler 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 commentedon Aug 27, 2026
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 commentedon Aug 28, 2026
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.
grantfox-oss commentedon Aug 28, 2026
🦊 GrantFox — @Ezeh20 has been assigned to this issue as part of the Third Campaign campaign!
Next steps:
Closes #153)Good luck! Track your progress on GrantFox.
grantfox-oss commentedon Aug 30, 2026
🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!
@Ezeh20's PR #156 was approved and merged by @Kaylahray.
🏆 @Ezeh20: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (395 total points). Track your full progress on GrantFox.
👏 Great work, @Ezeh20! Keep contributing to learnault.