Dead-Letter Queues for Undecodable Blockchain Events
Quarantine failed records with safe diagnostic context, preserve original evidence and replay deliberately after correcting a decoder or schema problem.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Some records cannot be processed immediately. A dead-letter path isolates those failures so they can be reviewed without either blocking every record or silently disappearing from the dataset.
Keep failure evidence bounded
Store event identity, safe error class, parser version and a reference to retained raw evidence. Limit payload size and remove secrets. Distinguish malformed input from an unsupported but valid event. Retry budgets should eventually lead to a reviewable state rather than an endless hot loop.
Worked example: an unknown event version
A contract upgrade emits an event the current parser cannot interpret. The consumer retains the raw event and marks the derived view partial. After a versioned parser update, an authorised replay processes the quarantined event using the same evidence identity. It does not create a second independent transfer.
Make replay a controlled operation
Filter replay by reason, version and range, and record the outcome. Test duplicate replays and a still-failing record. A dead-letter queue is not a completeness claim: reports should expose affected coverage or interpretation gaps. Retention must keep enough evidence for repair while respecting privacy and storage constraints.
A practical acceptance test
Feed an unsupported event version alongside supported records. Verify that supported work progresses and the failed record remains identifiable with a safe reason. Upgrade the parser and replay only the selected quarantine set twice. Exactly one derived interpretation should result, and coverage should stop claiming an unresolved decoding gap only after successful repair.
Questions about the topic
Frequently asked questions
Does quarantine mean the chain event is invalid?
No. It can mean the current parser does not support it.
Should replay generate new event identities?
No. Keep the original evidence identity and version the interpretation.
Standards & technical documentation
