How to Read a Protocol Post-Mortem

When something breaks, the document a team publishes afterwards tells you more about them than anything on their website. It is written under pressure, it is checkable against on-chain reality, and the choices about what to include are revealing.

Why the document matters beyond the incident

Post-mortems are one of the few places where a team is forced to describe their own engineering process under conditions where the on-chain record can contradict them. That makes them unusually hard to fake and unusually informative — often more informative about how a protocol is run than any amount of documentation written in calmer conditions.

They are also the main mechanism by which the industry learns anything. Most exploits repeat a known pattern, and the reason they keep repeating is that the accounts which would have taught the next team were never written.

What a credible one contains

A timeline with real timestamps. When the vulnerability was introduced, when it was exploited, when the team became aware, when they acted, when users were told. The gap between “became aware” and “users were told” is one of the most informative numbers in the document.

A root cause, not a trigger. “An attacker called function X with an unexpected parameter” is a trigger. The root cause is why that parameter was not validated, and beyond that, why the review process did not catch it. Teams routinely stop at the trigger because the trigger blames an attacker and the root cause blames a process.

Specific impact. Exact amounts, exact addresses, exact number of accounts. Vagueness here — “a limited number of users” — is nearly always doing work.

What was tried and did not work. Real incidents involve failed mitigations. A response with no missteps has been sanitised.

Dated, specific remediation. “We will improve our security processes” is not remediation. “We have added invariant tests for X, moved the admin key behind a 48-hour timelock as of date, and engaged a second auditor for the Y module” is.

The evasions

Passive voice around decisions. “It was determined that the pause would not be triggered” is hiding a person who decided not to pause. Watch specifically for passive constructions clustering around the choices, while the technical narrative stays active. That asymmetry is deliberate more often than not.

Blaming a dependency. An oracle, a bridge, a library, an auditor. Sometimes accurate, always incomplete: the team chose the dependency and chose not to bound its failure.

“Sophisticated attacker.” Occasionally true. Far more often it is a way of implying the failure was unforeseeable. Many exploits use well-documented techniques against a known vulnerability class.

Leading with the recovery. A document whose first three paragraphs describe how much was recovered and whose root cause appears on page two is a communications artefact.

The unexplained gap. Timelines that jump from detection to resolution with several hours unaccounted for. Something happened in that window.

Reading between the sections

Two questions are worth asking of every post-mortem, and neither is usually answered directly.

Was this class of bug known? Most exploits fall into well-understood categories — reentrancy, oracle manipulation, access control, rounding, upgrade errors. If the root cause is a category with published literature and standard mitigations, the real finding is why standard mitigations were not applied.

Could the team have detected it sooner? Many incidents run for hours or longer before anyone notices, and the detection gap is a monitoring problem entirely within the team’s control.

The strongest signal

No post-mortem at all.

Teams that do not publish are usually not protecting a technical secret; they are hoping the incident recedes. It does not — it just stays associated with them permanently, because nothing was ever put in its place. Publishing an honest account, including the parts that reflect badly, is both the right thing and reliably the better outcome, which is a pleasant coincidence and one that surprisingly few teams act on.