The migration and deployment checklist

Graduate · enrolled learners

This lesson opens with Uranium Finance, April 2021.

What happened

Uranium Finance ran an exchange on BNB Chain and migrated to a second version of its contracts. Its trading pairs enforced a balance invariant using a numeric constant, and during the migration that constant was changed inconsistently: one place in the calculation was updated to 10000 while a related factor stayed at 1000, a factor-of-ten mismatch. With the invariant check now wrong, an attacker could swap almost the entire reserves of a pair out of it while putting almost nothing in, because the broken check no longer enforced that value in must roughly match value out, and they drained about 50 million dollars. The individual contracts were not novel and the math was not exotic; the flaw was introduced by the migration itself, a single constant changed in one place and not another, and because the change lived in the new deployment it was invisible to any test written against the old version. A disciplined migration review, diffing every changed constant and re-checking that the invariants still held in the migrated code, would have caught a factor-of-ten mismatch immediately, but that review was not done, and the mismatch shipped.

The decision point

Migrations and deployments are the highest-risk moments in a contract's life, because they change the code that holds value and do so in ways the existing tests, written against the old version, cannot see, so a single inconsistent value introduced during a migration can be both invisible to the old tests and catastrophic once live. Uranium Finance is the case: a numeric constant in a pair's balance invariant was changed to 10000 in one place while a related factor stayed at 1000, a factor-of-ten mismatch that broke the check enforcing value-in-matches-value-out, and an attacker swapped almost the entire reserves out for almost nothing, draining about 50 million dollars, all from one constant changed in one place and not another. This is the deployment lesson that closes the course: the danger is not only in writing new code but in changing existing code, because a migration disturbs the assumptions the old tests encoded and can introduce a flaw that no old test covers and no casual glance catches. So the discipline is a migration and deployment checklist run every time: diff every value that changed and confirm each change is intended and consistent, re-verify that the contract's invariants still hold in the migrated code rather than assuming they carry over, and test the migrated state directly rather than trusting the tests of the version you left behind. Uranium Finance is what a migration without that discipline produces: a factor-of-ten typo in a constant, invisible to the old tests and worth 50 million dollars to whoever noticed it, which is exactly the kind of change a checklist exists to catch and a deploy in a hurry ships.

Recorded loss

$50,000,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.