How state is really laid out

Graduate · enrolled learners

This lesson opens with Team Finance, October 2022.

What happened

Team Finance offered token-locking and vesting services, holding users' locked liquidity in its contracts. When it ran a migration to move that locked liquidity from an older version of an exchange to a newer one, a flaw in the migration logic let an attacker manipulate the process and drain about 14.5 million dollars. Nothing cryptographic was broken and no signing key was stolen: the failure lived in how the contract's stored state, the locked positions and balances, was moved and re-established as the system was upgraded. A migration takes state that means one thing under the old code and re-lays it under the new code, and if the mapping between the two is wrong the stored assumptions no longer hold. Team Finance was most fragile at exactly that moment, because its stored truth was being rewritten, and the attacker exploited the gap between what the state meant before the migration and what the new code assumed it meant after.

The decision point

A contract is not only its code but its stored state, held in numbered storage slots whose meaning is defined entirely by the code that reads them, so state has no inherent meaning of its own; it means whatever the current code says it means. Team Finance is the case: a migration that moved locked liquidity between exchange versions contained a flaw in how it re-established that stored state, and an attacker used the gap between the old meaning of the state and the new code's assumptions to drain about 14.5 million dollars, without breaking any cryptography. This is why a builder must understand how state is really laid out, in slots, interpreted by code, before moving or reinterpreting it: an upgrade or migration is precisely the operation that rewrites what the stored bytes mean, and the moment the reading code changes but the stored bytes do not, or the bytes are moved without matching the new layout, the contract's assumptions about its own state can be silently false. So the discipline is to treat storage layout as load-bearing ground: know which slot holds which variable, know that the meaning of a slot is only the code's interpretation of it, and treat every migration and upgrade as a dangerous re-mapping of state that must be reasoned through slot by slot, because the state does not carry its meaning with it. Team Finance is what happens when state is moved as though it carried its own meaning: the new code and the old bytes disagreed, and the attacker lived in the disagreement.

Recorded loss

$14,500,000

Orientation and Year One are open: anyone can read them without an account. From Year Two onward the lessons are for enrolled learners, because progress through the later years only means anything if it is tracked against a record.

It is free. We do not sell the list and there is nothing to buy at the end of it.