Decoding Events Across Smart-Contract Upgrades
Version contract interfaces by historical execution context, so proxy upgrades do not cause old events to be decoded using today’s implementation assumptions.
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.
An upgradeable address can execute different implementations over time. A decoder that always uses the latest ABI risks changing the meaning of earlier records.
Resolve the historical interface
Keep proxy address, implementation context, block and decoder version. The exact discovery method depends on the proxy design. Event signatures help identify formats, but names alone do not establish field semantics. Preserve raw topics and data so a corrected historical interface can be applied later.
Worked example: a changed field meaning
Before an upgrade, an event field represents gross amount; afterward a similarly named field represents net amount. A current decoder can produce syntactically valid values for both while assigning the wrong meaning to old records. Version the interpretation by the implementation and execution boundary, not by the date the parser happens to run.
Test the upgrade boundary
Include transactions immediately before and after the implementation change and an event from an unsupported implementation. Record partial interpretation rather than guessing. Do not rewrite the original log when correcting a decoder: regenerate derived records with the new version and retain the evidence needed to explain the correction.
A practical acceptance test
Decode events immediately before and after a fixture implementation change using their respective interfaces. Add an unknown implementation and require partial interpretation. Re-run with a corrected parser and retain the same raw log identities. The new result should identify its decoder revision instead of pretending that the historical chain event itself changed.
Questions about the topic
Frequently asked questions
Is an address always one immutable interface?
No. Proxy-based execution can change implementations.
Should raw logs be replaced after a decoder correction?
No. Retain evidence and version the derived interpretation.
Standards & technical documentation